model-eol 0.9.1 → 0.10.0

package/README.md

@@ -73,7 +73,7 @@ node check.mjs path/to/your/repo --days 90
 <summary><b>Every command</b> - PR gate, distributor clocks, SBOM, badges, migration plans</summary>
 
 ```sh
-# PR gate: flag only lines THIS change adds relative to the base ref
+# PR gate: report only findings THIS change adds or makes newly actionable
 node check.mjs check . --changed origin/main --days 90
 # the same repo judged by a distributor's clock instead of the publisher's
 node check.mjs path/to/your/repo --via aws-bedrock
@@ -144,9 +144,13 @@ the `v0` line:
     scope: direct
 ```
 
-This is the PR gate. It fails only when *this* change adds a model that is
-retired or retiring within the threshold. Add `via: aws-bedrock` (or
-`azure-ai-foundry`) to judge by a distributor's clock.
+This is the PR gate. It reports the findings *this* change adds or makes newly
+actionable, and fails when one is retired or retiring within the threshold: a
+model on an added line, or an unchanged reference the change makes bad (a
+`.model-eol.json` edit, nearby SDK or cloud code, a rename, an in-repo feeds
+change, an untracked file). References already bad at the base ref stay out of
+the way. Add `via: aws-bedrock` (or `azure-ai-foundry`) to judge by a
+distributor's clock.
 
 A copy-paste workflow with both gates, the PR diff and a weekly full-repository
 check, is in

package/check.mjs

@@ -48,7 +48,8 @@ import {
   formatInventoryCycloneDX,
   formatSchedule,
 } from './lib/reports.mjs'
-import { addedLinesForTargets, filterFindingsToChanged, gitRootFor, incompleteScanNotes, scanTargets } from './lib/scanner.mjs'
+import { BaseUnavailableError, inCheckScope, selectChangedFindings } from './lib/changed.mjs'
+import { gitRootFor, incompleteScanNotes, scanTargets } from './lib/scanner.mjs'
 import { DOCUMENT_TYPES, formatDocumentErrors, validateDocumentFile } from './lib/validate-document.mjs'
 import { SUPPORTED_RECEIPT_SCHEMAS, VERIFY_INPUTS, VerifyError, formatVerification, printable, verifyReceipt } from './lib/verify.mjs'
 
@@ -98,6 +99,76 @@ const repoPathForFile = (file, roots) => {
   return normalizeRepoPath(candidates[0]?.relative ?? absolute)
 }
 
+const policyError = (config, feedData, via) => {
+  const allowedVias = new Set([...BUILTIN_CHANNELS, ...feedData.vias])
+  const unknownVia = [via, ...configuredVias(config)]
+    .find(value => value && !allowedVias.has(value))
+  if (unknownVia) return `unknown lifecycle channel "${unknownVia}"; known values: ${[...allowedVias].sort().join(', ')}`
+  const unresolvedRoute = config.routes.find(route => route.model && !feedData.entries.has(route.model))
+  if (unresolvedRoute) return `configured route model "${unresolvedRoute.model}" is not present in loaded feeds`
+  return null
+}
+
+const evaluateTargets = ({ targets, config, roots, ignoredFiles, feedData, overrides, includeDocs, noGit = false, classificationPathFor = null }) => {
+  const policyCache = new Map()
+  const policyForFile = file => {
+    const absolute = path.resolve(file)
+    if (!policyCache.has(absolute)) {
+      const repoPath = repoPathForFile(absolute, roots)
+      policyCache.set(absolute, { ...configForRepoPath(config, repoPath), repoPath })
+    }
+    return policyCache.get(absolute)
+  }
+  const routeForReference = ({ file, matched, id }) => {
+    const policy = policyForFile(file)
+    return routeForRepoReference(config, policy.repoPath, { matched, id })
+  }
+  const mappedRoutesForFile = file => {
+    const policy = policyForFile(file)
+    return mappedRoutesForRepoPath(config, policy.repoPath)
+  }
+
+  const scan = scanTargets({
+    targets,
+    entries: feedData.entries,
+    keys: feedData.keys,
+    includeDocs,
+    ignoreRoots: roots,
+    ignoredFiles,
+    policyForFile,
+    routeForReference,
+    mappedRoutesForFile,
+    noGit,
+    classificationPathFor,
+  })
+
+  const findings = scan.modelRefs.map(ref => {
+    const policy = policyForFile(ref.file)
+    const route = routeForReference({ file: ref.file, matched: ref.matched, id: ref.id })
+    const days = overrides.days ?? policy.days
+    const scope = overrides.scope ?? policy.scope
+    const via = overrides.via ?? (route?.via ?? policy.via)
+    const finding = findingFromRef(ref, { days, via })
+    finding.effective_scope = scope
+    finding.requested_via = via
+    if (policy.override_indexes.length || route) {
+      finding.policy_provenance = {
+        override_indexes: policy.override_indexes,
+        route_index: route?.index ?? null,
+      }
+    }
+    return finding
+  })
+  for (const candidate of scan.candidateRefs) {
+    const policy = policyForFile(candidate.file)
+    candidate.effective_scope = overrides.scope ?? policy.scope
+    if (policy.override_indexes.length) {
+      candidate.policy_provenance = { override_indexes: policy.override_indexes, route_index: null }
+    }
+  }
+  return { scan, findings, checkFindings: findings.filter(inCheckScope) }
+}
+
 const main = () => {
 const COMMANDS = new Set(['check', 'inventory', 'schedule', 'alert', 'plan', 'apply', 'validate', 'verify', 'help'])
 const args = process.argv.slice(2)
@@ -168,8 +239,10 @@ Usage:
 
 Commands:
   check       Fail when tracked model IDs are retired or retiring within --days.
-              With --changed BASE_REF, answer the PR CI question: "this PR ADDS a
-              dependency on a model that already has a death date".
+              With --changed BASE_REF, report findings this change adds or makes newly
+              actionable: every reference on an added line, and unchanged references that
+              a config, feeds, rename, nearby-code, or untracked-file change made bad.
+              References already bad at BASE_REF are not reported.
   inventory   List tracked model references plus direct/cloud/gateway integration hints.
               --format json is the machine-readable default; --format cyclonedx emits a CycloneDX 1.6 ML-BOM.
   schedule    Show the retirement schedule for tracked references in the target.
@@ -366,50 +439,30 @@ if (feedData.entries.size === 0) {
   return 2
 }
 
-const allowedVias = new Set([...BUILTIN_CHANNELS, ...feedData.vias])
-const unknownVia = [values.via, ...configuredVias(repositoryConfig)]
-  .find(via => via && !allowedVias.has(via))
-if (unknownVia) {
-  console.error(`unknown lifecycle channel "${unknownVia}"; known values: ${[...allowedVias].sort().join(', ')}`)
-  return 2
-}
-const unresolvedRoute = repositoryConfig.routes.find(route => route.model && !feedData.entries.has(route.model))
-if (unresolvedRoute) {
-  console.error(`configured route model "${unresolvedRoute.model}" is not present in loaded feeds`)
+const headPolicyError = policyError(repositoryConfig, feedData, values.via)
+if (headPolicyError) {
+  console.error(headPolicyError)
   return 2
 }
 
-const policyCache = new Map()
-const policyForFile = file => {
-  const absolute = path.resolve(file)
-  if (!policyCache.has(absolute)) {
-    const repoPath = repoPathForFile(absolute, configLocation.roots)
-    policyCache.set(absolute, { ...configForRepoPath(repositoryConfig, repoPath), repoPath })
-  }
-  return policyCache.get(absolute)
-}
-const routeForReference = ({ file, matched, id }) => {
-  const policy = policyForFile(file)
-  return routeForRepoReference(repositoryConfig, policy.repoPath, { matched, id })
+const overrides = {
+  days: values.days === undefined ? undefined : DAYS,
+  scope: values.scope === undefined ? undefined : SCOPE,
+  via: values.via === undefined ? undefined : VIA,
 }
-const mappedRoutesForFile = file => {
-  const policy = policyForFile(file)
-  return mappedRoutesForRepoPath(repositoryConfig, policy.repoPath)
-}
-
 let scan
+let findings
+let checkFindings
 try {
-  scan = scanTargets({
+  ({ scan, findings, checkFindings } = evaluateTargets({
     targets,
-    entries: feedData.entries,
-    keys: feedData.keys,
-    includeDocs: INCLUDE_DOCS,
-    ignoreRoots: configLocation.roots,
+    config: repositoryConfig,
+    roots: configLocation.roots,
     ignoredFiles: configLocation.file ? [configLocation.file] : [],
-    policyForFile,
-    routeForReference,
-    mappedRoutesForFile,
-  })
+    feedData,
+    overrides,
+    includeDocs: INCLUDE_DOCS,
+  }))
 } catch (e) {
   console.error(`scan failed: ${e.message}`)
   return 2
@@ -426,36 +479,56 @@ if (incompleteNotes.length && (command === 'check' || command === 'plan')) {
   if (!ALLOW_INCOMPLETE) return 2
 }
 
-const findings = scan.modelRefs.map(ref => {
-  const policy = policyForFile(ref.file)
-  const route = routeForReference({ file: ref.file, matched: ref.matched, id: ref.id })
-  const days = values.days === undefined ? policy.days : DAYS
-  const scope = values.scope === undefined ? policy.scope : SCOPE
-  const via = values.via === undefined ? (route?.via ?? policy.via) : VIA
-  const finding = findingFromRef(ref, { days, via })
-  finding.effective_scope = scope
-  finding.requested_via = via
-  if (policy.override_indexes.length || route) {
-    finding.policy_provenance = {
-      override_indexes: policy.override_indexes,
-      route_index: route?.index ?? null,
+const evaluateBase = ({ treeRoot, files, configFile, feedsDir, classificationPathFor }) => {
+  let config = repositoryConfig
+  let baseFeeds = feedData
+  try {
+    if (configFile === null) config = normalizeConfig({}, { defaults: CLI_DEFAULT_CONFIG })
+    else if (configFile !== undefined) config = loadConfig(configFile, { defaults: DEFAULT_CONFIG, allowMissing: false })
+  } catch (e) {
+    throw new BaseUnavailableError(`failed to load base config: ${e.message}`)
+  }
+  if (feedsDir !== undefined) {
+    try {
+      baseFeeds = loadFeeds(feedsDir)
+    } catch (e) {
+      throw new BaseUnavailableError(`failed to load base feeds: ${e.message}`)
     }
+    if (baseFeeds.entries.size === 0) throw new BaseUnavailableError('no feed entries loaded from base feeds')
   }
-  return finding
-})
-for (const candidate of scan.candidateRefs) {
-  const policy = policyForFile(candidate.file)
-  candidate.effective_scope = values.scope === undefined ? policy.scope : SCOPE
-  if (policy.override_indexes.length) {
-    candidate.policy_provenance = { override_indexes: policy.override_indexes, route_index: null }
+  const basePolicyError = policyError(config, baseFeeds, values.via)
+  if (basePolicyError) throw new BaseUnavailableError(`base policy: ${basePolicyError}`)
+  try {
+    const base = evaluateTargets({
+      targets: files,
+      config,
+      roots: [treeRoot],
+      ignoredFiles: configFile ? [configFile] : [],
+      feedData: baseFeeds,
+      overrides,
+      includeDocs: INCLUDE_DOCS,
+      noGit: true,
+      classificationPathFor,
+    })
+    return { findings: base.findings, notes: base.scan.notes }
+  } catch (e) {
+    throw new BaseUnavailableError(`base scan failed: ${e.message}`)
   }
 }
-const checkFindings = findings.filter(finding =>
-  finding.effective_scope !== 'direct' || finding.usage === 'direct-api' || finding.usage === 'model-reference')
+
 let changedFindings = checkFindings
 if (CHANGED_BASE !== null) {
   try {
-    changedFindings = filterFindingsToChanged(checkFindings, addedLinesForTargets(targets, CHANGED_BASE))
+    changedFindings = selectChangedFindings({
+      targets,
+      baseRef: CHANGED_BASE,
+      findings,
+      checkFindings,
+      scannedFiles: scan.files,
+      configFile: configLocation.file,
+      feedsDir: FEEDS_DIR,
+      evaluateBase,
+    })
   } catch (e) {
     console.error(`--changed failed: ${e.message}`)
     return 2

package/examples/workflows/model-eol.yml

@@ -1,8 +1,9 @@
 # model-eol - copy this file to .github/workflows/model-eol.yml in YOUR repo.
 #
 # Two gates:
-#   - every PR: fail only if THIS change adds a model that is retired or
-#     retiring within the threshold (existing references stay out of the way)
+#   - every PR: fail only if THIS change adds or makes newly actionable a model
+#     that is retired or retiring within the threshold (references that were
+#     already bad at the base stay out of the way)
 #   - weekly: full-repository check, so legacy references surface on a schedule
 #     instead of in an outage
 #

package/lib/changed.mjs

@@ -0,0 +1,493 @@
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { spawnSync } from 'node:child_process'
+
+import { isBad } from './feeds.mjs'
+import { MAX_FILE_BYTES, SKIP_DIRS, baseLineFor, changedLinesForTargets, displayPath, incompleteScanNotes, isAddedLine } from './scanner.mjs'
+
+export class BaseUnavailableError extends Error {
+  constructor(message) {
+    super(message)
+    this.name = 'BaseUnavailableError'
+  }
+}
+
+export const inCheckScope = finding =>
+  finding.effective_scope !== 'direct' || finding.usage === 'direct-api' || finding.usage === 'model-reference'
+
+const MAX_SYMLINK_DEPTH = 40
+const SUBMODULE_GIT_CONFIG = ['-c', 'protocol.allow=never', '-c', 'core.fsmonitor=false']
+
+const runGit = (gitRoot, label, args, { input, hardened = false } = {}) => {
+  const result = spawnSync('git', hardened ? [...SUBMODULE_GIT_CONFIG, ...args] : args, {
+    cwd: gitRoot,
+    input,
+    env: hardened ? { ...process.env, GIT_NO_LAZY_FETCH: '1' } : process.env,
+    stdio: [input === undefined ? 'ignore' : 'pipe', 'pipe', 'pipe'],
+    maxBuffer: 1024 * 1024 * 1024,
+  })
+  if (result.error || result.status !== 0) {
+    const detail = String(result.stderr ?? '').trim() || result.error?.message || `exit ${result.status}`
+    throw new Error(`git ${label} failed: ${detail}`)
+  }
+  return result.stdout
+}
+
+const nulRecords = buffer => buffer.toString('utf8').split('\0').filter(Boolean)
+
+const repoRelative = (gitRoot, absolute) => {
+  const relative = path.relative(gitRoot, absolute)
+  if (relative === '..' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) return null
+  return relative.split(path.sep).join('/')
+}
+
+const onDiskName = (directory, name) => {
+  try {
+    const names = fs.readdirSync(directory)
+    if (names.includes(name)) return name
+    const wanted = fs.lstatSync(path.join(directory, name))
+    return names.find(other => {
+      const stat = fs.lstatSync(path.join(directory, other))
+      return stat.dev === wanted.dev && stat.ino === wanted.ino
+    }) ?? name
+  } catch {
+    return name
+  }
+}
+
+const lexicalRepoPath = (gitRoot, absolute) => {
+  const parts = path.resolve(absolute).split(path.sep)
+  for (let index = 1; index <= parts.length; index++) {
+    let real
+    try {
+      real = fs.realpathSync(parts.slice(0, index).join(path.sep) || path.sep)
+    } catch {
+      return null
+    }
+    if (real !== gitRoot) continue
+    const names = []
+    for (const part of parts.slice(index)) names.push(onDiskName(path.join(gitRoot, ...names), part))
+    return names.join('/')
+  }
+  return null
+}
+
+const nativeRealpath = target => {
+  try {
+    return fs.realpathSync.native(target)
+  } catch {
+    return null
+  }
+}
+
+const repoLocation = (gitRoot, target) => {
+  const physical = nativeRealpath(target)
+  const lexical = lexicalRepoPath(gitRoot, target)
+  // path.resolve folds "link/.." before the OS follows link, so trust the lexical path only when both agree.
+  if (lexical !== null && (physical === null || nativeRealpath(path.resolve(target)) === physical)) return lexical
+  return physical === null ? null : repoRelative(gitRoot, physical)
+}
+
+const isIgnored = (gitRoot, relative) => {
+  if (relative === '') return false
+  const result = spawnSync('git', ['check-ignore', '-q', '--', `./${relative}`], {
+    cwd: gitRoot,
+    encoding: 'utf8',
+    stdio: ['ignore', 'ignore', 'pipe'],
+  })
+  if (!result.error && (result.status === 0 || result.status === 1)) return result.status === 0
+  const detail = String(result.stderr ?? '').trim() || result.error?.message || `exit ${result.status}`
+  if (result.status === 128 && /in submodule|beyond a symbolic link/i.test(detail)) return false
+  throw new Error(`git check-ignore failed: ${detail}`)
+}
+
+const readRegular = absolute => {
+  let descriptor
+  try {
+    descriptor = fs.openSync(absolute, fs.constants.O_RDONLY | (fs.constants.O_NONBLOCK ?? 0))
+  } catch (error) {
+    return error.code === 'ENOENT' ? { bytes: null } : { message: error.message }
+  }
+  try {
+    return fs.fstatSync(descriptor).isFile() ? { bytes: fs.readFileSync(descriptor) } : { message: 'not a regular file' }
+  } catch (error) {
+    return { message: error.message }
+  } finally {
+    fs.closeSync(descriptor)
+  }
+}
+
+const readHead = absolute => {
+  const result = readRegular(absolute)
+  if (result.message) throw new Error(`could not read ${absolute}: ${result.message}`)
+  return result.bytes
+}
+
+const scannableTreePath = relative => relative.split('/').every(part =>
+  part && part !== '.' && part !== '..' && part.toLowerCase() !== '.git' && !SKIP_DIRS.has(part))
+
+const regularBlob = entry => entry.type === 'blob' && (entry.mode === '100644' || entry.mode === '100755')
+
+const untrackedFiles = (gitRoot, relativeTargets) => new Set(nulRecords(runGit(gitRoot, 'ls-files', [
+  '--literal-pathspecs', 'ls-files', '-z', '--others', '--exclude-standard', '--', ...relativeTargets,
+])).filter(relative => !relative.endsWith('/')).map(relative => path.resolve(gitRoot, relative)))
+
+const parseTree = output => {
+  const entries = new Map()
+  for (const record of nulRecords(output)) {
+    const separator = record.indexOf('\t')
+    const [mode, type, oid, size] = record.slice(0, separator).split(/ +/)
+    if (separator === -1 || !/^[0-7]{6}$/.test(mode) || !/^[0-9a-f]{40,64}$/.test(oid ?? '')) {
+      throw new Error('git ls-tree returned a malformed record')
+    }
+    entries.set(record.slice(separator + 1), { mode, type, oid, size: size === '-' ? null : Number(size) })
+  }
+  return entries
+}
+
+const readBlobs = (gitRoot, entries, { hardened = false } = {}) => {
+  const output = runGit(gitRoot, 'cat-file', ['cat-file', '--batch'], { input: entries.map(entry => `${entry.oid}\n`).join(''), hardened })
+  const blobs = []
+  let offset = 0
+  for (const entry of entries) {
+    const newline = output.indexOf(0x0a, offset)
+    if (newline === -1) throw new Error('git cat-file returned a truncated record')
+    const [oid, type, size] = output.toString('utf8', offset, newline).split(' ')
+    if (oid !== entry.oid || type !== 'blob' || !/^\d+$/.test(size ?? '')) {
+      throw new Error(`git cat-file could not read blob ${entry.oid}`)
+    }
+    const start = newline + 1
+    const end = start + Number(size)
+    if (end + 1 > output.length) throw new Error('git cat-file returned a truncated record')
+    blobs.push(output.subarray(start, end))
+    offset = end + 1
+  }
+  return blobs
+}
+
+const baseTreeReader = (gitRoot, baseCommit, { hardened = false } = {}) => {
+  const lsTree = (pathspecs, { recursive = false } = {}) => parseTree(runGit(gitRoot, 'ls-tree', [
+    '--literal-pathspecs', 'ls-tree', ...(recursive ? ['-r'] : []), '-z', '-l', '--full-tree', baseCommit,
+    ...(pathspecs.length ? ['--', ...pathspecs] : []),
+  ], { hardened }))
+  const entries = new Map()
+  const lookup = relative => {
+    if (!entries.has(relative)) entries.set(relative, lsTree([relative]).get(relative) ?? null)
+    return entries.get(relative)
+  }
+  const blobs = new Map()
+  const read = entry => {
+    if (!blobs.has(entry.oid)) blobs.set(entry.oid, readBlobs(gitRoot, [entry], { hardened })[0])
+    return blobs.get(entry.oid)
+  }
+  const children = relative => [...lsTree(relative === '' ? [] : [`${relative}/`])].map(([child, entry]) => ({
+    name: relative === '' ? child : child.slice(relative.length + 1),
+    entry,
+  }))
+  const followTarget = (parent, target, depth) => {
+    const parts = target.split('/')
+    let current = parent
+    let unresolved = false
+    for (const [index, part] of parts.entries()) {
+      if (part === '' || part === '.') continue
+      if (part !== '..') {
+        current = current ? `${current}/${part}` : part
+        unresolved = true
+        continue
+      }
+      if (unresolved) {
+        const directory = resolve(current, depth + 1)
+        if (directory.state !== 'tree') {
+          return { result: directory.state === 'absent' ? { state: 'absent' } : { state: 'unavailable', message: `symbolic link target ${target} does not resolve to a directory` } }
+        }
+        current = directory.relative
+        unresolved = false
+      }
+      if (current === '') return { escaped: path.join(path.dirname(gitRoot), ...parts.slice(index + 1)) }
+      current = path.posix.dirname(current) === '.' ? '' : path.posix.dirname(current)
+    }
+    return { relative: current }
+  }
+  const resolve = (relative, depth = 0) => {
+    if (depth > MAX_SYMLINK_DEPTH) return { state: 'unavailable', message: 'too many levels of symbolic links' }
+    const parts = relative === '' ? [] : relative.split('/')
+    for (let index = 1; index <= parts.length; index++) {
+      const prefix = parts.slice(0, index).join('/')
+      const entry = lookup(prefix)
+      if (!entry) return { state: 'absent' }
+      const rest = parts.slice(index)
+      if (entry.mode === '160000') return { state: 'submodule', prefix, commit: entry.oid, rest: rest.join('/') }
+      if (entry.mode === '120000') {
+        const target = read(entry).toString('utf8')
+        const parent = path.posix.dirname(prefix) === '.' ? '' : path.posix.dirname(prefix)
+        if (path.posix.isAbsolute(target) && target.split('/').includes('..')) {
+          return { state: 'unavailable', message: `absolute symbolic link target ${target} contains ..` }
+        }
+        const followed = path.posix.isAbsolute(target) ? { escaped: path.resolve(target) } : followTarget(parent, target, depth)
+        if (followed.result) return followed.result
+        if (followed.relative !== undefined) return resolve([followed.relative, ...rest].filter(Boolean).join('/'), depth + 1)
+        const absolute = followed.escaped
+        const inside = repoRelative(gitRoot, absolute) ?? lexicalRepoPath(gitRoot, absolute)
+        if (inside === null) return { state: 'outside', absolute: path.join(absolute, ...rest) }
+        return resolve([inside, ...rest].filter(Boolean).join('/'), depth + 1)
+      }
+      if (rest.length && entry.type !== 'tree') return { state: 'absent' }
+      if (!rest.length && entry.type !== 'tree') {
+        return regularBlob(entry) ? { state: 'blob', entry } : { state: 'unavailable', message: 'not a regular file' }
+      }
+    }
+    return { state: 'tree', relative }
+  }
+  return { root: gitRoot, hardened, lsTree, read, children, resolve }
+}
+
+const submoduleReader = (reader, prefix, commit) => {
+  const unavailable = { state: 'unavailable', message: `in submodule ${prefix}, which is not checked out with base commit ${commit}` }
+  const candidate = path.join(reader.root, ...prefix.split('/'))
+  let root
+  try {
+    root = fs.realpathSync(candidate)
+    // A PR can commit a directory laid out as a git dir, but never a .git entry or a gitlink's checkout.
+    if (root !== candidate || !fs.lstatSync(root).isDirectory() || !fs.existsSync(path.join(root, '.git'))) return unavailable
+    const index = runGit(reader.root, 'ls-files', ['--literal-pathspecs', 'ls-files', '-s', '-z', '--', prefix], { hardened: reader.hardened })
+    if (!nulRecords(index).some(record => record.startsWith('160000 ') && record.endsWith(`\t${prefix}`))) return unavailable
+    const toplevel = runGit(root, 'rev-parse', ['rev-parse', '--show-toplevel'], { hardened: true }).toString('utf8').trim()
+    if (fs.realpathSync(toplevel) !== root) return unavailable
+  } catch {
+    return unavailable
+  }
+  const present = spawnSync('git', [...SUBMODULE_GIT_CONFIG, 'cat-file', '-e', `${commit}^{commit}`], {
+    cwd: root,
+    env: { ...process.env, GIT_NO_LAZY_FETCH: '1' },
+    stdio: 'ignore',
+  })
+  return present.status === 0 ? baseTreeReader(root, commit, { hardened: true }) : unavailable
+}
+
+const resolveBase = (reader, relative, depth = 0) => {
+  const resolved = reader.resolve(relative)
+  if (resolved.state !== 'submodule') return { ...resolved, reader }
+  if (depth > MAX_SYMLINK_DEPTH) return { state: 'unavailable', message: 'too many nested submodules' }
+  const submodule = submoduleReader(reader, resolved.prefix, resolved.commit)
+  return submodule.state === 'unavailable' ? submodule : resolveBase(submodule, resolved.rest, depth + 1)
+}
+
+const sameBytes = (left, right) => left === null || right === null ? left === right : left.equals(right)
+
+const configInput = ({ gitRoot, tree, configFile }) => {
+  const location = repoLocation(gitRoot, configFile ?? path.join(gitRoot, '.model-eol.json'))
+  if (location === null || location === '') return { changed: false }
+  const resolved = resolveBase(tree, location)
+  if (resolved.state === 'absent' && isIgnored(gitRoot, location)) return { changed: false }
+  const head = configFile ? readHead(configFile) : null
+  const base = resolved.state === 'blob' ? { bytes: resolved.reader.read(resolved.entry) }
+    : resolved.state === 'absent' ? { bytes: null }
+      : resolved.state === 'outside' ? readRegular(resolved.absolute)
+        : { message: resolved.message ?? 'a directory' }
+  if (base.message) return { changed: true, location, unavailable: `base config ${location} is ${base.message}` }
+  return { changed: !sameBytes(head, base.bytes), location, bytes: base.bytes }
+}
+
+const readFeedDirectory = directory => {
+  const files = new Map()
+  for (const name of fs.readdirSync(directory).filter(name => name.endsWith('.json'))) {
+    const result = readRegular(path.join(directory, name))
+    if (result.message || result.bytes === null) return { message: `entry ${name} is ${result.message ?? 'missing'}` }
+    files.set(name, result.bytes)
+  }
+  return { files }
+}
+
+const feedsInput = ({ gitRoot, tree, feedsDir }) => {
+  const location = repoLocation(gitRoot, feedsDir)
+  if (location === null) return { changed: false }
+  const directory = resolveBase(tree, location)
+  if (directory.state === 'absent' && isIgnored(gitRoot, location)) return { changed: false }
+  const label = location || '.'
+  const headFiles = readFeedDirectory(feedsDir)
+  if (headFiles.message) throw new Error(`could not read feeds ${feedsDir}: ${headFiles.message}`)
+  const head = headFiles.files
+  const unavailable = message => ({ changed: true, location, unavailable: `base feeds ${message}` })
+  let base
+  if (directory.state === 'tree') {
+    base = new Map()
+    const { reader } = directory
+    for (const { name, entry } of reader.children(directory.relative)) {
+      if (!name.endsWith('.json')) continue
+      const resolved = regularBlob(entry) ? { state: 'blob', entry, reader }
+        : entry.mode === '120000' ? resolveBase(reader, directory.relative ? `${directory.relative}/${name}` : name)
+          : null
+      const outside = resolved?.state === 'outside' ? readRegular(resolved.absolute) : null
+      if (resolved?.state === 'blob') base.set(name, resolved.reader.read(resolved.entry))
+      else if (outside?.bytes) base.set(name, outside.bytes)
+      else return unavailable(`entry ${label}/${name} is not a readable regular file at base`)
+    }
+  } else if (directory.state === 'outside') {
+    let listed
+    try {
+      listed = readFeedDirectory(directory.absolute)
+    } catch (error) {
+      return unavailable(`directory ${label} could not be read at base: ${error.message}`)
+    }
+    if (listed.message) return unavailable(`directory ${label} at base: ${listed.message}`)
+    base = listed.files
+  } else if (directory.state === 'unavailable') {
+    return unavailable(`directory ${label} is ${directory.message}`)
+  } else {
+    return unavailable(`directory ${label} is ${directory.state === 'absent' ? 'missing' : 'not a directory'} at base`)
+  }
+  const changed = head.size !== base.size || [...head].some(([name, bytes]) => !base.has(name) || !bytes.equals(base.get(name)))
+  return { changed, location, files: base }
+}
+
+const temporaryRoot = gitRoot => {
+  const tmp = fs.realpathSync(os.tmpdir())
+  if (repoRelative(gitRoot, tmp) !== null) {
+    throw new Error(`the temporary directory ${tmp} is inside the git repository; set TMPDIR to a directory outside it`)
+  }
+  return fs.realpathSync(fs.mkdtempSync(path.join(tmp, 'model-eol-base-')))
+}
+
+const findingKey = (relative, line, id, matched) => JSON.stringify([relative, line, id, matched])
+
+const baseSummary = finding => ({
+  status: finding.status,
+  via: finding.via,
+  usage: finding.usage,
+  threshold_days: finding.threshold_days,
+  effective_scope: finding.effective_scope,
+})
+
+export const selectChangedFindings = ({ targets, baseRef, findings, checkFindings, scannedFiles, configFile, feedsDir, evaluateBase }) => {
+  const diff = changedLinesForTargets(targets, baseRef)
+  const { gitRoot, baseCommit } = diff
+  const tree = baseTreeReader(gitRoot, baseCommit)
+  const untracked = untrackedFiles(gitRoot, diff.relativeTargets)
+  const config = configInput({ gitRoot, tree, configFile })
+  const feeds = feedsInput({ gitRoot, tree, feedsDir })
+  const sharedInputs = [...(config.changed ? ['config'] : []), ...(feeds.changed ? ['feeds'] : [])]
+
+  const affected = new Map()
+  for (const file of scannedFiles) {
+    const absolute = path.resolve(file)
+    const record = diff.files.get(absolute)
+    const isUntracked = untracked.has(absolute)
+    const inputs = [
+      ...sharedInputs,
+      ...(record?.renamed ? ['rename'] : []),
+      ...(record?.hunks.length ? ['file'] : []),
+      ...(isUntracked ? ['untracked'] : []),
+    ]
+    if (!inputs.length) continue
+    affected.set(absolute, {
+      inputs,
+      baseRelative: isUntracked ? null : record ? record.basePath : repoRelative(gitRoot, absolute),
+      hunks: record?.hunks ?? [],
+    })
+  }
+
+  const occurrences = new Map()
+  const seen = new Map()
+  for (const finding of findings) {
+    const key = findingKey(path.resolve(finding.file), finding.line, finding.id, finding.matched)
+    const index = seen.get(key) ?? 0
+    seen.set(key, index + 1)
+    occurrences.set(finding, index)
+  }
+
+  const candidates = checkFindings.filter(finding =>
+    !isAddedLine(diff.added, finding.file, finding.line) && isBad(finding) && affected.has(path.resolve(finding.file)))
+  const baseRelatives = [...new Set(candidates
+    .map(finding => affected.get(path.resolve(finding.file)).baseRelative)
+    .filter(relative => relative !== null))]
+
+  const baseFindings = new Map()
+  const incomplete = new Set()
+  let unavailable = (config.changed && config.unavailable) || (feeds.changed && feeds.unavailable) || null
+  if (baseRelatives.length && unavailable === null) {
+    const tempRoot = temporaryRoot(gitRoot)
+    try {
+      const treeRoot = path.join(tempRoot, 'tree')
+      fs.mkdirSync(treeRoot)
+      const listing = tree.lsTree(diff.relativeTargets, { recursive: true })
+      const writes = []
+      for (const relative of baseRelatives) {
+        const entry = listing.get(relative)
+        if (!entry || !scannableTreePath(relative)) continue
+        if (!regularBlob(entry) || entry.size > MAX_FILE_BYTES) {
+          incomplete.add(relative)
+          continue
+        }
+        writes.push({ relative, entry, target: path.join(treeRoot, ...relative.split('/')) })
+      }
+      const blobs = writes.length ? readBlobs(gitRoot, writes.map(write => write.entry)) : []
+      const files = []
+      for (const [index, write] of writes.entries()) {
+        try {
+          fs.mkdirSync(path.dirname(write.target), { recursive: true })
+          fs.writeFileSync(write.target, blobs[index], { flag: 'wx' })
+          files.push(write.target)
+        } catch {
+          incomplete.add(write.relative)
+        }
+      }
+      const replacements = [[`${treeRoot}${path.sep}`, `${baseRef}:`], [treeRoot, `${baseRef}:`]]
+      let baseConfigFile
+      if (config.changed) {
+        baseConfigFile = null
+        if (config.bytes !== null) {
+          baseConfigFile = path.join(tempRoot, 'config', path.posix.basename(config.location))
+          fs.mkdirSync(path.dirname(baseConfigFile))
+          fs.writeFileSync(baseConfigFile, config.bytes, { flag: 'wx' })
+          replacements.unshift([baseConfigFile, `${baseRef}:${config.location}`])
+        }
+      }
+      let baseFeedsDir
+      if (feeds.changed) {
+        baseFeedsDir = path.join(tempRoot, 'feeds')
+        fs.mkdirSync(baseFeedsDir)
+        for (const [name, bytes] of feeds.files) fs.writeFileSync(path.join(baseFeedsDir, name), bytes, { flag: 'wx' })
+        replacements.unshift([`${baseFeedsDir}${path.sep}`, `${baseRef}:${feeds.location ? `${feeds.location}/` : ''}`], [baseFeedsDir, `${baseRef}:${feeds.location || '.'}`])
+      }
+      if (files.length) {
+        const relativeToTree = file => path.relative(treeRoot, path.resolve(file)).split(path.sep).join('/')
+        try {
+          const base = evaluateBase({
+            treeRoot,
+            files,
+            configFile: baseConfigFile,
+            feedsDir: baseFeedsDir,
+            classificationPathFor: file => displayPath(path.join(gitRoot, ...relativeToTree(file).split('/'))),
+          })
+          for (const note of incompleteScanNotes(base.notes)) if (note.file) incomplete.add(relativeToTree(note.file))
+          for (const finding of base.findings) {
+            const key = findingKey(relativeToTree(finding.file), finding.line, finding.id, finding.matched)
+            if (!baseFindings.has(key)) baseFindings.set(key, [])
+            baseFindings.get(key).push(finding)
+          }
+        } catch (error) {
+          if (!(error instanceof BaseUnavailableError)) throw error
+          unavailable = replacements.reduce((message, [from, to]) => message.split(from).join(to), error.message)
+        }
+      }
+    } finally {
+      fs.rmSync(tempRoot, { recursive: true, force: true })
+    }
+  }
+
+  return checkFindings.flatMap(finding => {
+    if (isAddedLine(diff.added, finding.file, finding.line)) return [{ ...finding, changed: { reason: 'added-line' } }]
+    const file = isBad(finding) ? affected.get(path.resolve(finding.file)) : null
+    if (!file) return []
+    const newlyActionable = base => [{ ...finding, changed: { reason: 'newly-actionable', inputs: [...file.inputs], base } }]
+    if (file.baseRelative === null) return newlyActionable(null)
+    if (unavailable !== null) return [{ ...finding, changed: { reason: 'base-unavailable', message: unavailable } }]
+    const baseLine = baseLineFor(file.hunks, finding.line)
+    if (baseLine === null || incomplete.has(file.baseRelative)) return newlyActionable(null)
+    const match = baseFindings.get(findingKey(file.baseRelative, baseLine, finding.id, finding.matched))?.[occurrences.get(finding)]
+    if (!match) return newlyActionable(null)
+    if (isBad(match) && inCheckScope(match)) return []
+    return newlyActionable(baseSummary(match))
+  })
+}

package/lib/reports.mjs

@@ -1,6 +1,7 @@
 import { isBad } from './feeds.mjs'
 import { color } from './color.mjs'
 import { incompleteScanNotes } from './scanner.mjs'
+import { printable } from './verify.mjs'
 
 export const marker = status =>
   status === 'retired' ? '✗' :
@@ -196,6 +197,28 @@ export const buildAlert = schedule => {
   }
 }
 
+const CHANGED_INPUT_LABELS = new Map([
+  ['config', 'config changed'],
+  ['feeds', 'feeds changed'],
+  ['rename', 'file renamed'],
+  ['file', 'nearby lines changed'],
+  ['untracked', 'untracked file'],
+])
+
+const changedTail = finding => {
+  const changed = finding.changed
+  if (changed?.reason === 'base-unavailable') return `  [base unavailable: ${printable(changed.message)}]`
+  if (changed?.reason !== 'newly-actionable') return ''
+  const inputs = changed.inputs.map(input => CHANGED_INPUT_LABELS.get(input) ?? printable(input)).join(', ')
+  const base = changed.base
+  const outOfScope = base && (base.status === 'retired' || base.status === 'retiring') &&
+    base.effective_scope === 'direct' && base.usage !== 'direct-api' && base.usage !== 'model-reference'
+  const was = !base
+    ? 'no finding at base'
+    : `was ${base.status}${base.via && base.via !== 'publisher' ? ` via ${printable(base.via)}` : ''}${outOfScope ? ` but out of direct scope (${base.usage})` : ''} at base`
+  return `  [newly actionable: ${inputs}; ${was}]`
+}
+
 export const formatCheck = ({ findings, bad, scannedFiles, days, scope }) => {
   const out = []
   if (findings.length === 0) {
@@ -203,7 +226,7 @@ export const formatCheck = ({ findings, bad, scannedFiles, days, scope }) => {
   }
   for (const f of findings) {
     const where = `${f.file}:${f.line}`
-    out.push(humanFinding(f, `${marker(f.status)} ${where}  ${f.matched}  ${findingTail(f, days)}${f.via && f.via !== 'publisher' ? `  [via ${f.via}]` : ''}`))
+    out.push(humanFinding(f, `${marker(f.status)} ${where}  ${f.matched}  ${findingTail(f, days)}${f.via && f.via !== 'publisher' ? `  [via ${f.via}]` : ''}${changedTail(f)}`))
   }
   if (bad.length) out.push(`\n${color('bold', `model-eol: ${bad.length} finding(s) at or past the ${days}-day threshold`)}`)
   return out.join('\n')

package/lib/scanner.mjs

@@ -153,7 +153,7 @@ const isScannable = (file, includeDocs) => {
 
 const escapeRegExp = value => value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
 
-const displayPath = absolute => {
+export const displayPath = absolute => {
   const relative = path.relative(process.cwd(), absolute)
   return relative && !relative.startsWith(`..${path.sep}`) && relative !== '..' && !path.isAbsolute(relative)
     ? relative
@@ -227,14 +227,19 @@ const decodeGitQuotedPath = raw => {
   return decoded
 }
 
-export const parseDiffPath = value => {
-  const raw = value.endsWith('\r') ? value.slice(0, -1) : value
+const decodeDiffPath = value => {
+  const line = value.endsWith('\r') ? value.slice(0, -1) : value
+  // Git appends a tab to ---/+++ names that contain a space; a literal tab in a name is always quoted.
+  const raw = line.endsWith('\t') ? line.slice(0, -1) : line
   const decoded = raw.startsWith('"') ? decodeGitQuotedPath(raw) : raw
-  if (decoded === '/dev/null') return null
-  return decoded.startsWith('b/') ? decoded.slice(2) : decoded
+  return decoded === '/dev/null' ? null : decoded
 }
 
-export const addedLinesForTargets = (targets, baseRef) => {
+const stripDiffPrefix = (decoded, prefix) => decoded !== null && decoded.startsWith(prefix) ? decoded.slice(prefix.length) : decoded
+
+export const parseDiffPath = value => stripDiffPrefix(decodeDiffPath(value), 'b/')
+
+export const resolveChangedRepository = (targets, baseRef) => {
   if (!baseRef) throw new Error('--changed requires a base ref')
   const roots = new Set()
   const resolvedTargets = []
@@ -279,13 +284,21 @@ export const addedLinesForTargets = (targets, baseRef) => {
     const detail = (resolvedBase.stderr ?? '').trim()
     throw new Error(`--changed could not resolve base ref "${baseRef}" to a commit${detail ? `: ${detail}` : ''}`)
   }
+  return { gitRoot, baseCommit, relativeTargets }
+}
+
+export const changedLinesForTargets = (targets, baseRef) => {
+  const { gitRoot, baseCommit, relativeTargets } = resolveChangedRepository(targets, baseRef)
+  const { GIT_DIFF_OPTS, ...env } = process.env
   const result = spawnSync('git', [
-    '-c', 'core.quotePath=true',
-    'diff', '--no-color', '--src-prefix=a/', '--dst-prefix=b/',
+    '-c', 'core.quotePath=true', '-c', 'diff.relative=false', '--literal-pathspecs',
+    'diff', '--no-color', '--src-prefix=a/', '--dst-prefix=b/', '--find-renames',
+    '--diff-algorithm=myers', '--indent-heuristic', '--inter-hunk-context=0',
     '--text', '--no-ext-diff', '--no-textconv', '--unified=0', baseCommit, '--', ...relativeTargets,
   ], {
     cwd: gitRoot,
     encoding: 'utf8',
+    env,
     stdio: ['ignore', 'pipe', 'pipe'],
   })
   if (result.error || result.status !== 0) {
@@ -294,27 +307,69 @@ export const addedLinesForTargets = (targets, baseRef) => {
   }
 
   const added = new Set()
+  const files = new Map()
+  let header = null
   let file = null
+  let record = null
   let inHunk = false
   let newLine = 0
   let newLinesRemaining = 0
+  const recordFor = headPath => {
+    const absolute = path.resolve(gitRoot, headPath)
+    if (!files.has(absolute)) {
+      files.set(absolute, {
+        headPath,
+        basePath: header.renameFrom ?? header.minusPath,
+        renamed: header.renameFrom !== null && header.renameFrom !== headPath,
+        hunks: [],
+      })
+    }
+    return files.get(absolute)
+  }
+  const finishHeader = () => {
+    if (header && !record && header.renameTo !== null) recordFor(header.renameTo)
+  }
   for (const line of result.stdout.split('\n')) {
     if (line.startsWith('diff --git ')) {
+      finishHeader()
+      header = { minusPath: null, renameFrom: null, renameTo: null }
       file = null
+      record = null
       inHunk = false
       newLinesRemaining = 0
       continue
     }
+    if (header && !inHunk) {
+      if (line.startsWith('rename from ')) {
+        header.renameFrom = decodeDiffPath(line.slice('rename from '.length))
+        continue
+      }
+      if (line.startsWith('rename to ')) {
+        header.renameTo = decodeDiffPath(line.slice('rename to '.length))
+        continue
+      }
+      if (line.startsWith('--- ')) {
+        header.minusPath = stripDiffPrefix(decodeDiffPath(line.slice(4)), 'a/')
+        continue
+      }
+    }
     if (!inHunk && line.startsWith('+++ ')) {
       const relative = parseDiffPath(line.slice(4))
       file = relative ? path.resolve(gitRoot, relative) : null
+      record = relative && header ? recordFor(relative) : null
       continue
     }
-    const hunk = line.match(/^@@ -\d+(?:,\d+)? \+(\d+)(?:,(\d+))? @@/)
+    const hunk = line.match(/^@@ -(\d+)(?:,(\d+))? \+(\d+)(?:,(\d+))? @@/)
     if (hunk) {
       inHunk = true
-      newLine = Number(hunk[1])
-      newLinesRemaining = hunk[2] === undefined ? 1 : Number(hunk[2])
+      newLine = Number(hunk[3])
+      newLinesRemaining = hunk[4] === undefined ? 1 : Number(hunk[4])
+      record?.hunks.push({
+        oldStart: Number(hunk[1]),
+        oldCount: hunk[2] === undefined ? 1 : Number(hunk[2]),
+        newStart: newLine,
+        newCount: newLinesRemaining,
+      })
       continue
     }
     // Unified-diff metadata such as "\" does not
@@ -327,11 +382,26 @@ export const addedLinesForTargets = (targets, baseRef) => {
       newLinesRemaining--
     }
   }
-  return added
+  finishHeader()
+  return { gitRoot, baseCommit, relativeTargets, added, files }
 }
 
+export const addedLinesForTargets = (targets, baseRef) => changedLinesForTargets(targets, baseRef).added
+
+export const baseLineFor = (hunks, line) => {
+  let offset = 0
+  for (const hunk of hunks) {
+    const newEnd = hunk.newCount === 0 ? hunk.newStart : hunk.newStart + hunk.newCount - 1
+    if (hunk.newCount > 0 && line >= hunk.newStart && line <= newEnd) return null
+    if (newEnd < line) offset += hunk.newCount - hunk.oldCount
+  }
+  return line - offset
+}
+
+export const isAddedLine = (addedLines, file, line) => addedLines.has(changedKey(file, line))
+
 export const filterFindingsToChanged = (findings, addedLines) =>
-  findings.filter(finding => addedLines.has(changedKey(finding.file, finding.line)))
+  findings.filter(finding => isAddedLine(addedLines, finding.file, finding.line))
 
 const collectFilesDetailed = (targets, {
   includeDocs = false,
@@ -339,6 +409,7 @@ const collectFilesDetailed = (targets, {
   ignoreRoots = [],
   ignoredFiles = [],
   policyForFile = null,
+  noGit = false,
 } = {}) => {
   const files = []
   const notes = []
@@ -472,7 +543,7 @@ const collectFilesDetailed = (targets, {
   const listGitFiles = (absoluteTarget, gitRoot) => {
     const relativeTarget = path.relative(gitRoot, absoluteTarget) || '.'
     const result = spawnSync('git', [
-      'ls-files', '-z', '--cached', '--others', '--exclude-standard', '--', relativeTarget,
+      '--literal-pathspecs', 'ls-files', '-z', '--cached', '--others', '--exclude-standard', '--', relativeTarget,
     ], {
       cwd: gitRoot,
       encoding: 'utf8',
@@ -488,7 +559,7 @@ const collectFilesDetailed = (targets, {
       return
     }
     const tracked = spawnSync('git', [
-      'ls-files', '-z', '--cached', '--stage', '--', relativeTarget,
+      '--literal-pathspecs', 'ls-files', '-z', '--cached', '--stage', '--', relativeTarget,
     ], {
       cwd: gitRoot,
       encoding: 'utf8',
@@ -557,7 +628,7 @@ const collectFilesDetailed = (targets, {
     } catch {
       resolvedTarget = absoluteTarget
     }
-    const gitRoot = gitRootFor(resolvedTarget)
+    const gitRoot = noGit ? null : gitRootFor(resolvedTarget)
     if (gitRoot) listGitFiles(resolvedTarget, gitRoot)
     else walk(absoluteTarget)
   }
@@ -579,8 +650,10 @@ export const scanTargets = ({
   policyForFile = null,
   routeForReference = null,
   mappedRoutesForFile = null,
+  noGit = false,
+  classificationPathFor = null,
 }) => {
-  const collected = collectFilesDetailed(targets, { includeDocs, ignorePaths, ignoreRoots, ignoredFiles, policyForFile })
+  const collected = collectFilesDetailed(targets, { includeDocs, ignorePaths, ignoreRoots, ignoredFiles, policyForFile, noGit })
   if (collected.validTargets.length === 0) throw new Error('no valid targets remain')
   const { files } = collected
   const pattern = buildModelPattern(keys)
@@ -665,6 +738,7 @@ export const scanTargets = ({
   }
 
   for (const file of files) {
+    const classifiedFile = classificationPathFor ? classificationPathFor(file) : file
     let bytes
     try {
       bytes = fs.readFileSync(file)
@@ -732,7 +806,7 @@ export const scanTargets = ({
           const record = entries.get(m[1])
           const route = routeForReference?.({ file, matched: m[1], id: record.entry.id }) ?? null
           const classification = route ? routeClassification(route) : classifyRef({
-            file,
+            file: classifiedFile,
             line: i + 1,
             lines,
             publisher: record.publisher,
@@ -755,7 +829,7 @@ export const scanTargets = ({
         if (mappedSources.has(candidate) || isKnownModel(candidate, entries) || obviousCandidateNoise(candidate)) continue
         if (ignoresModel(file, candidate)) continue
         const classification = classifyRef({
-          file,
+          file: classifiedFile,
           line: i + 1,
           lines,
           publisher: 'unknown',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "model-eol",
-  "version": "0.9.1",
+  "version": "0.10.0",
   "description": "AI model deprecation feeds with a zero-dependency checker, inventory CLI, and migration bot.",
   "type": "module",
   "bin": {

package/schema/model-eol.check.schema.json

@@ -49,9 +49,61 @@
         "requested_via": { "type": ["string", "null"], "minLength": 1 },
         "waiver": { "$ref": "https://thossullivan.github.io/model-eol/schema/0.1/model-eol.inventory.schema.json#/definitions/waiver" },
         "policy_provenance": { "$ref": "https://thossullivan.github.io/model-eol/schema/0.1/model-eol.inventory.schema.json#/definitions/policyProvenance" },
-        "mapped_from": { "type": "string", "minLength": 1 }
+        "mapped_from": { "type": "string", "minLength": 1 },
+        "changed": { "$ref": "#/definitions/changed" }
       },
       "additionalProperties": false
+    },
+    "changed": {
+      "description": "Present only with --changed: why the finding is reported for this change.",
+      "oneOf": [
+        {
+          "type": "object",
+          "required": ["reason"],
+          "properties": { "reason": { "const": "added-line" } },
+          "additionalProperties": false
+        },
+        {
+          "type": "object",
+          "required": ["reason", "inputs", "base"],
+          "properties": {
+            "reason": { "const": "newly-actionable" },
+            "inputs": {
+              "type": "array",
+              "minItems": 1,
+              "uniqueItems": true,
+              "items": { "enum": ["config", "feeds", "rename", "file", "untracked"] }
+            },
+            "base": {
+              "oneOf": [
+                { "type": "null" },
+                {
+                  "type": "object",
+                  "required": ["status", "via", "usage", "threshold_days", "effective_scope"],
+                  "properties": {
+                    "status": { "$ref": "https://thossullivan.github.io/model-eol/schema/0.1/model-eol.inventory.schema.json#/definitions/status" },
+                    "via": { "type": ["string", "null"], "minLength": 1 },
+                    "usage": { "$ref": "https://thossullivan.github.io/model-eol/schema/0.1/model-eol.inventory.schema.json#/definitions/usage" },
+                    "threshold_days": { "type": "integer", "minimum": 0 },
+                    "effective_scope": { "enum": ["all", "direct"] }
+                  },
+                  "additionalProperties": false
+                }
+              ]
+            }
+          },
+          "additionalProperties": false
+        },
+        {
+          "type": "object",
+          "required": ["reason", "message"],
+          "properties": {
+            "reason": { "const": "base-unavailable" },
+            "message": { "type": "string", "minLength": 1 }
+          },
+          "additionalProperties": false
+        }
+      ]
     }
   }
 }