model-eol 0.4.0 → 0.5.0

package/lib/scanner.mjs

@@ -1,6 +1,7 @@
 import fs from 'node:fs'
 import path from 'node:path'
 import { spawnSync } from 'node:child_process'
+import { TextDecoder } from 'node:util'
 
 import { buildModelPattern } from './feeds.mjs'
 import { matchesAnyGlob, matchesGlob, normalizeRepoPath } from './glob.mjs'
@@ -25,10 +26,16 @@ export const INCOMPLETE_SCAN_REASONS = new Set([
   'unreadable-file',
   'unreadable-path',
   'unreadable-directory',
+  'invalid-utf8',
+  'symlink-skipped',
+  'submodule-skipped',
+  'nested-repository-skipped',
   'file-count-cap',
   'git-listing-failure',
 ])
 
+const utf8Decoder = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true })
+
 export const incompleteScanNotes = notes => notes.filter(note => INCOMPLETE_SCAN_REASONS.has(note.reason))
 
 export const scanIsIncomplete = notes => incompleteScanNotes(notes).length > 0
@@ -167,17 +174,63 @@ export const gitRootFor = target => {
 
 const changedKey = (file, line) => `${path.resolve(file)}:${line}`
 
-const parseDiffPath = value => {
-  const raw = value.trim()
-  if (raw === '/dev/null') return null
-  let decoded = raw
-  if (raw.startsWith('"')) {
-    try {
-      decoded = JSON.parse(raw)
-    } catch {
-      decoded = raw.slice(1, raw.endsWith('"') ? -1 : undefined)
+const gitPathEscapes = new Map([
+  ['a', 0x07],
+  ['b', 0x08],
+  ['t', 0x09],
+  ['n', 0x0a],
+  ['v', 0x0b],
+  ['f', 0x0c],
+  ['r', 0x0d],
+  ['\\', 0x5c],
+  ['"', 0x22],
+])
+
+const decodeGitQuotedPath = raw => {
+  if (!raw.endsWith('"')) throw new Error(`malformed quoted Git diff path: ${raw}`)
+  const bytes = []
+  let literalStart = 1
+  const appendLiteral = end => {
+    if (end > literalStart) bytes.push(...Buffer.from(raw.slice(literalStart, end), 'utf8'))
+  }
+  for (let index = 1; index < raw.length - 1; index++) {
+    const character = raw[index]
+    if (character === '"') throw new Error(`malformed quoted Git diff path: ${raw}`)
+    if (character !== '\\') continue
+    appendLiteral(index)
+    index++
+    if (index >= raw.length - 1) throw new Error(`malformed quoted Git diff path: ${raw}`)
+    const escaped = raw[index]
+    if (/[0-7]/.test(escaped)) {
+      let octal = escaped
+      while (octal.length < 3 && index + 1 < raw.length - 1 && /[0-7]/.test(raw[index + 1])) {
+        octal += raw[++index]
+      }
+      const value = Number.parseInt(octal, 8)
+      if (value > 0xff) throw new Error(`invalid octal escape in Git diff path: ${raw}`)
+      bytes.push(value)
+    } else if (gitPathEscapes.has(escaped)) {
+      bytes.push(gitPathEscapes.get(escaped))
+    } else {
+      throw new Error(`unsupported escape in Git diff path: ${raw}`)
     }
+    literalStart = index + 1
+  }
+  appendLiteral(raw.length - 1)
+  let decoded
+  try {
+    decoded = utf8Decoder.decode(Buffer.from(bytes))
+  } catch {
+    throw new Error(`Git diff path is not valid UTF-8: ${raw}`)
   }
+  if (decoded.includes('\0')) throw new Error(`Git diff path contains a NUL byte: ${raw}`)
+  return decoded
+}
+
+export const parseDiffPath = value => {
+  const raw = value.endsWith('\r') ? value.slice(0, -1) : value
+  const decoded = raw.startsWith('"') ? decodeGitQuotedPath(raw) : raw
+  if (decoded === '/dev/null') return null
   return decoded.startsWith('b/') ? decoded.slice(2) : decoded
 }
 
@@ -211,7 +264,26 @@ export const addedLinesForTargets = (targets, baseRef) => {
     }
     return relative || '.'
   })
-  const result = spawnSync('git', ['diff', '--unified=0', baseRef, '--', ...relativeTargets], {
+  if (baseRef.startsWith('-')) {
+    throw new Error(`--changed base ref must not begin with "-": ${JSON.stringify(baseRef)}`)
+  }
+  const resolvedBase = spawnSync('git', [
+    'rev-parse', '--verify', '--quiet', '--end-of-options', `${baseRef}^{commit}`,
+  ], {
+    cwd: gitRoot,
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+  })
+  const baseCommit = (resolvedBase.stdout ?? '').trim()
+  if (resolvedBase.error || resolvedBase.status !== 0 || !/^(?:[0-9a-f]{40}|[0-9a-f]{64})$/.test(baseCommit)) {
+    const detail = (resolvedBase.stderr ?? '').trim()
+    throw new Error(`--changed could not resolve base ref "${baseRef}" to a commit${detail ? `: ${detail}` : ''}`)
+  }
+  const result = spawnSync('git', [
+    '-c', 'core.quotePath=true',
+    'diff', '--no-color', '--src-prefix=a/', '--dst-prefix=b/',
+    '--text', '--no-ext-diff', '--no-textconv', '--unified=0', baseCommit, '--', ...relativeTargets,
+  ], {
     cwd: gitRoot,
     encoding: 'utf8',
     stdio: ['ignore', 'pipe', 'pipe'],
@@ -245,6 +317,9 @@ export const addedLinesForTargets = (targets, baseRef) => {
       newLinesRemaining = hunk[2] === undefined ? 1 : Number(hunk[2])
       continue
     }
+    // Unified-diff metadata such as "\" does not
+    // consume a line on either side of the hunk.
+    if (line.startsWith('\\ ')) continue
     if (!inHunk || !file || newLinesRemaining === 0) continue
     if (line.startsWith('+')) added.add(changedKey(file, newLine))
     if (!line.startsWith('-')) {
@@ -278,20 +353,22 @@ const collectFilesDetailed = (targets, {
     }
   }
   const excludedFiles = new Set(ignoredFiles.map(canonicalPath))
-  const roots = ignoreRoots.map(canonicalPath)
+  const roots = [...new Set(ignoreRoots.flatMap(root => [path.resolve(root), canonicalPath(root)]))]
   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))
+    const candidates = [...new Set([path.resolve(absolute), canonicalPath(absolute)])]
+    const repoPaths = new Set()
+    for (const candidate of candidates) {
+      for (const root of roots) {
+        const relative = path.relative(root, candidate)
+        if (relative === '' || relative === '..' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) continue
+        repoPaths.add(normalizeRepoPath(relative))
+      }
     }
-    return repoPaths
+    return [...repoPaths]
   }
   const matchesIgnoredRepoPath = repoPath => matchesAnyGlob(repoPath, ignorePaths) ||
     ignorePaths.some(pattern => {
@@ -300,9 +377,12 @@ const collectFilesDetailed = (targets, {
     })
   const isIgnoredFile = absolute => {
     const resolved = canonicalPath(absolute)
-    if (excludedFiles.has(resolved) || repoPathsFor(resolved).some(matchesIgnoredRepoPath)) return true
-    const policy = policyForFile?.(resolved)
-    return Boolean(policy?.repoPath && matchesIgnoredRepoPathWithPatterns(policy.repoPath, policy.ignore?.paths ?? []))
+    if (excludedFiles.has(resolved) || repoPathsFor(absolute).some(matchesIgnoredRepoPath)) return true
+    const policyPaths = [...new Set([path.resolve(absolute), resolved])]
+    return policyPaths.some(candidate => {
+      const policy = policyForFile?.(candidate)
+      return Boolean(policy?.repoPath && matchesIgnoredRepoPathWithPatterns(policy.repoPath, policy.ignore?.paths ?? []))
+    })
   }
   const matchesIgnoredRepoPathWithPatterns = (repoPath, patterns) => matchesAnyGlob(repoPath, patterns) ||
     patterns.some(pattern => {
@@ -327,7 +407,11 @@ const collectFilesDetailed = (targets, {
       note({ reason: 'unreadable-file', file: displayPath(absolute), message: e.message })
       return
     }
-    if (!st.isFile() || st.isSymbolicLink() || !isScannable(absolute, includeDocs)) return
+    if (st.isSymbolicLink()) {
+      if (!isIgnoredFile(absolute)) note({ reason: 'symlink-skipped', file: displayPath(absolute) })
+      return
+    }
+    if (!st.isFile() || !isScannable(absolute, includeDocs)) return
     if (st.size > MAX_FILE_BYTES) {
       note({
         reason: 'file-too-large',
@@ -362,7 +446,10 @@ const collectFilesDetailed = (targets, {
       note({ reason: 'unreadable-path', file: displayPath(absolute), message: e.message })
       return
     }
-    if (st.isSymbolicLink()) return
+    if (st.isSymbolicLink()) {
+      if (!isIgnoredFile(absolute)) note({ reason: 'symlink-skipped', file: displayPath(absolute) })
+      return
+    }
     if (!st.isDirectory()) {
       addFile(absolute)
       return
@@ -400,10 +487,50 @@ const collectFilesDetailed = (targets, {
       })
       return
     }
+    const tracked = spawnSync('git', [
+      'ls-files', '-z', '--cached', '--stage', '--', relativeTarget,
+    ], {
+      cwd: gitRoot,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'pipe'],
+    })
+    if (tracked.error || tracked.status !== 0) {
+      const detail = tracked.error?.message || tracked.stderr?.trim() || `exit ${tracked.status}`
+      note({
+        reason: 'git-listing-failure',
+        file: displayPath(absoluteTarget),
+        message: `git index metadata listing failed: ${detail}; no recursive fallback used`,
+      })
+      return
+    }
+    const gitlinks = new Set()
+    for (const record of tracked.stdout.split('\0')) {
+      if (!record) continue
+      const separator = record.indexOf('\t')
+      const metadata = separator === -1 ? '' : record.slice(0, separator)
+      const relativeFile = separator === -1 ? '' : record.slice(separator + 1)
+      if (!/^[0-7]{6} [0-9a-f]+ [0-3]$/.test(metadata) || !relativeFile) {
+        note({
+          reason: 'git-listing-failure',
+          file: displayPath(absoluteTarget),
+          message: 'git index metadata listing returned a malformed record; no recursive fallback used',
+        })
+        return
+      }
+      if (metadata.startsWith('160000 ')) gitlinks.add(relativeFile)
+    }
     for (const relativeFile of result.stdout.split('\0')) {
       if (stopped) break
       if (!relativeFile) continue
       const absoluteFile = path.resolve(gitRoot, relativeFile)
+      if (gitlinks.has(relativeFile)) {
+        if (!isIgnoredFile(absoluteFile)) note({ reason: 'submodule-skipped', file: displayPath(absoluteFile) })
+        continue
+      }
+      if (relativeFile.endsWith('/')) {
+        if (!isIgnoredFile(absoluteFile)) note({ reason: 'nested-repository-skipped', file: displayPath(absoluteFile) })
+        continue
+      }
       if (path.relative(gitRoot, absoluteFile).split(path.sep).some(part => SKIP_DIRS.has(part))) continue
       addFile(absoluteFile)
     }
@@ -536,13 +663,20 @@ export const scanTargets = ({
   }
 
   for (const file of files) {
-    let text
+    let bytes
     try {
-      text = fs.readFileSync(file, 'utf8')
+      bytes = fs.readFileSync(file)
     } catch (e) {
       collected.notes.push({ reason: 'unreadable-file', file, message: e.message })
       continue
     }
+    let text
+    try {
+      text = utf8Decoder.decode(bytes)
+    } catch (e) {
+      collected.notes.push({ reason: 'invalid-utf8', file, message: e.message })
+      continue
+    }
     // Product artifacts and generated clients describe model IDs but are not
     // authoritative usage or safe migration targets.
     if (modelEolDocument(file, text)) {

package/lib/validate-document.mjs

@@ -0,0 +1,320 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import { TextDecoder } from 'node:util'
+
+import { normalizeConfig } from './config.mjs'
+import { JsonSchemaRegistry, validateJsonSchema } from './json-schema.mjs'
+import { validateFeed } from './validate-feed.mjs'
+
+export const DOCUMENT_TYPES = Object.freeze(['feed', 'config', 'check', 'inventory', 'schedule', 'alert', 'plan'])
+
+const SCHEMA_FILES = Object.freeze({
+  feed: 'model-eol.schema.json',
+  config: 'model-eol.bot-config.schema.json',
+  check: 'model-eol.check.schema.json',
+  inventory: 'model-eol.inventory.schema.json',
+  schedule: 'model-eol.schedule.schema.json',
+  alert: 'model-eol.alert.schema.json',
+  plan: 'model-eol.plan.schema.json',
+})
+
+const TYPE_ALIASES = new Map([
+  ['bot-config', 'config'],
+  ['model-eol-config', 'config'],
+])
+
+const utf8Decoder = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true })
+
+const SCHEMA_DISCRIMINATORS = new Map([
+  ['model-eol/check@0.1', 'check'],
+  ['model-eol/inventory@0.1', 'inventory'],
+  ['model-eol/schedule@0.1', 'schedule'],
+  ['model-eol/alert@0.1', 'alert'],
+])
+
+let catalogCache
+
+export const loadDocumentSchemaCatalog = () => {
+  if (catalogCache) return catalogCache
+  const directory = new URL('../schema/', import.meta.url)
+  const byType = new Map()
+  for (const type of DOCUMENT_TYPES) {
+    const file = new URL(SCHEMA_FILES[type], directory)
+    let schema
+    try {
+      schema = JSON.parse(fs.readFileSync(file, 'utf8'))
+    } catch (error) {
+      throw new Error(`failed to load ${type} schema: ${error.message}`)
+    }
+    byType.set(type, schema)
+  }
+  const registry = new JsonSchemaRegistry([...byType.values()])
+  registry.assertReferences()
+  const byId = new Map([...byType.entries()].map(([type, schema]) => [schema.$id, { type, schema }]))
+  catalogCache = { byType, byId, registry }
+  return catalogCache
+}
+
+export const normalizeDocumentType = value => {
+  if (typeof value !== 'string' || !value) return null
+  const normalized = TYPE_ALIASES.get(value) ?? value
+  return DOCUMENT_TYPES.includes(normalized) ? normalized : null
+}
+
+const isObject = value => value !== null && typeof value === 'object' && !Array.isArray(value)
+
+const configKeys = new Set([
+  'days', 'scope', 'via', 'feeds', 'ignore', 'overrides', 'routes', 'issues', 'eval',
+])
+
+export const detectDocumentType = (document, { file = null } = {}) => {
+  if (!isObject(document)) return null
+  if (typeof document.$schema === 'string' && typeof document.$id === 'string') return 'schema'
+  if (Object.hasOwn(document, 'spec')) return 'feed'
+  if (Object.hasOwn(document, 'plan_schema')) return 'plan'
+  if (typeof document.schema === 'string') return SCHEMA_DISCRIMINATORS.get(document.schema) ?? null
+  if (file && path.basename(file) === '.model-eol.json') return 'config'
+  const keys = Object.keys(document)
+  if (keys.length && keys.every(key => configKeys.has(key))) return 'config'
+  return null
+}
+
+const schemaDefinitionErrors = (document, catalog) => {
+  const errors = []
+  const fail = (path, keyword, message) => errors.push({ path, keyword, message })
+  if (!isObject(document)) return [{ path: '$', keyword: 'type', message: 'must be an object' }]
+  if (document.$schema !== 'http://json-schema.org/draft-07/schema#') {
+    fail('$.$schema', '$schema', 'must equal "http://json-schema.org/draft-07/schema#"')
+  }
+  const registered = catalog.byId.get(document.$id)
+  if (!registered) fail('$.$id', '$id', `must identify one of the ${catalog.byType.size} published model-eol schemas`)
+
+  const validTypes = new Set(['null', 'boolean', 'object', 'array', 'number', 'integer', 'string'])
+  const validFormats = new Set(['date', 'date-time', 'uri'])
+  const supportedKeywords = new Set([
+    '$schema', '$id', '$ref', '$comment',
+    'title', 'description', 'default', 'examples', 'readOnly', 'writeOnly',
+    'type', 'const', 'enum', 'format', 'pattern',
+    'minLength', 'maxLength', 'minimum', 'maximum',
+    'minItems', 'maxItems', 'uniqueItems', 'items',
+    'required', 'properties', 'additionalProperties', 'dependencies',
+    'definitions', 'allOf', 'oneOf',
+  ])
+  const childPath = (base, key) => `${base}.${key}`
+  const lint = (rule, at) => {
+    if (typeof rule === 'boolean') return
+    if (!isObject(rule)) {
+      fail(at, 'schema', 'must be an object or boolean schema')
+      return
+    }
+    for (const keyword of Object.keys(rule)) {
+      if (!supportedKeywords.has(keyword)) {
+        fail(childPath(at, keyword), keyword, `unsupported JSON Schema keyword ${keyword}`)
+      }
+    }
+    if (rule.$ref !== undefined && typeof rule.$ref !== 'string') fail(childPath(at, '$ref'), '$ref', 'must be a string')
+    if (rule.type !== undefined) {
+      const types = Array.isArray(rule.type) ? rule.type : [rule.type]
+      if (!types.length || types.some(type => typeof type !== 'string' || !validTypes.has(type))) {
+        fail(childPath(at, 'type'), 'type', 'must name one or more JSON types')
+      }
+    }
+    if (rule.required !== undefined && (!Array.isArray(rule.required) || rule.required.some(value => typeof value !== 'string'))) {
+      fail(childPath(at, 'required'), 'required', 'must be an array of property names')
+    }
+    if (rule.enum !== undefined && (!Array.isArray(rule.enum) || rule.enum.length === 0)) {
+      fail(childPath(at, 'enum'), 'enum', 'must be a non-empty array')
+    }
+    if (rule.format !== undefined && (typeof rule.format !== 'string' || !validFormats.has(rule.format))) {
+      fail(childPath(at, 'format'), 'format', 'must be date, date-time, or uri')
+    }
+    if (rule.pattern !== undefined) {
+      if (typeof rule.pattern !== 'string') fail(childPath(at, 'pattern'), 'pattern', 'must be a string')
+      else {
+        try {
+          new RegExp(rule.pattern)
+        } catch {
+          fail(childPath(at, 'pattern'), 'pattern', 'must be a valid regular expression')
+        }
+      }
+    }
+    for (const keyword of ['minLength', 'maxLength', 'minItems', 'maxItems']) {
+      if (rule[keyword] !== undefined && (!Number.isInteger(rule[keyword]) || rule[keyword] < 0)) {
+        fail(childPath(at, keyword), keyword, 'must be a non-negative integer')
+      }
+    }
+    if (rule.uniqueItems !== undefined && typeof rule.uniqueItems !== 'boolean') {
+      fail(childPath(at, 'uniqueItems'), 'uniqueItems', 'must be a boolean')
+    }
+    for (const keyword of ['minimum', 'maximum']) {
+      if (rule[keyword] !== undefined && (typeof rule[keyword] !== 'number' || !Number.isFinite(rule[keyword]))) {
+        fail(childPath(at, keyword), keyword, 'must be a finite number')
+      }
+    }
+    for (const keyword of ['properties', 'definitions']) {
+      if (rule[keyword] === undefined) continue
+      if (!isObject(rule[keyword])) {
+        fail(childPath(at, keyword), keyword, 'must be an object of schemas')
+        continue
+      }
+      for (const [name, child] of Object.entries(rule[keyword])) lint(child, `${at}.${keyword}[${JSON.stringify(name)}]`)
+    }
+    if (rule.items !== undefined) lint(rule.items, childPath(at, 'items'))
+    if (rule.additionalProperties !== undefined) lint(rule.additionalProperties, childPath(at, 'additionalProperties'))
+    for (const keyword of ['allOf', 'oneOf']) {
+      if (rule[keyword] === undefined) continue
+      if (!Array.isArray(rule[keyword]) || rule[keyword].length === 0) {
+        fail(childPath(at, keyword), keyword, 'must be a non-empty array of schemas')
+        continue
+      }
+      rule[keyword].forEach((child, index) => lint(child, `${at}.${keyword}[${index}]`))
+    }
+    if (rule.dependencies !== undefined) {
+      if (!isObject(rule.dependencies)) fail(childPath(at, 'dependencies'), 'dependencies', 'must be an object')
+      else {
+        for (const [name, dependency] of Object.entries(rule.dependencies)) {
+          const dependencyPath = `${at}.dependencies[${JSON.stringify(name)}]`
+          if (Array.isArray(dependency)) {
+            if (dependency.some(value => typeof value !== 'string')) fail(dependencyPath, 'dependencies', 'must contain property names')
+          } else lint(dependency, dependencyPath)
+        }
+      }
+    }
+  }
+  lint(document, '$')
+
+  if (registered) {
+    try {
+      const companionSchemas = [...catalog.byType.values()].filter(schema => schema.$id !== document.$id)
+      const registry = new JsonSchemaRegistry([document, ...companionSchemas])
+      registry.assertReferences()
+    } catch (error) {
+      fail('$', '$ref', error.message)
+    }
+  }
+  return errors
+}
+
+const semanticErrors = (document, type) => {
+  if (type === 'feed') {
+    return validateFeed(document).map(error => ({
+      path: error.path === 'feed' ? '$' : `$.${error.path}`,
+      keyword: 'model-eol-feed',
+      message: error.message,
+    }))
+  }
+  if (type === 'config') {
+    try {
+      normalizeConfig(document)
+      return []
+    } catch (error) {
+      return [{ path: '$', keyword: 'model-eol-config', message: error.message }]
+    }
+  }
+  if (type === 'plan') {
+    try {
+      validatePlanItems(document.items)
+      return []
+    } catch (error) {
+      return [{ path: '$.items', keyword: 'model-eol-plan', message: error.message }]
+    }
+  }
+  return []
+}
+
+export const validateDocument = (document, { type, file = null } = {}) => {
+  const selectedType = type === undefined || type === null
+    ? detectDocumentType(document, { file })
+    : normalizeDocumentType(type)
+  if (!selectedType) {
+    const detail = type
+      ? `unknown document type ${JSON.stringify(type)}`
+      : typeof document?.schema === 'string'
+        ? `unknown document schema ${JSON.stringify(document.schema)}`
+        : 'could not determine the document type'
+    return {
+      type: null,
+      errors: [{ path: '$', keyword: 'documentType', message: `${detail}; use --type ${DOCUMENT_TYPES.join('|')}` }],
+    }
+  }
+
+  const catalog = loadDocumentSchemaCatalog()
+  if (selectedType === 'schema') return { type: selectedType, errors: schemaDefinitionErrors(document, catalog) }
+  const { byType, registry } = catalog
+  const schemaErrors = validateJsonSchema(document, byType.get(selectedType), { registry })
+  return {
+    type: selectedType,
+    errors: schemaErrors.length ? schemaErrors : semanticErrors(document, selectedType),
+  }
+}
+
+export const formatDocumentErrors = errors => errors.map(error => `${error.path}: ${error.message}`)
+
+export const assertValidDocument = (document, options = {}) => {
+  const result = validateDocument(document, options)
+  if (result.errors.length) throw new Error(formatDocumentErrors(result.errors).join('\n'))
+  return { document, type: result.type }
+}
+
+export const validatePlanItems = items => {
+  if (!Array.isArray(items)) throw new Error('plan must contain an items array')
+  for (const [index, item] of items.entries()) {
+    if (!item || typeof item !== 'object' || Array.isArray(item)) {
+      throw new Error(`plan item ${index} must be an object`)
+    }
+    if (typeof item.file !== 'string' || item.file.length === 0) {
+      throw new Error(`plan item ${index} file must be a non-empty string`)
+    }
+    if (!Number.isInteger(item.line) || item.line < 1) {
+      throw new Error(`plan item ${index} line must be an integer >= 1`)
+    }
+    if (!Number.isInteger(item.occurrence) || item.occurrence < 0) {
+      throw new Error(`plan item ${index} occurrence must be an integer >= 0`)
+    }
+    if (typeof item.matched !== 'string' || item.matched.length === 0) {
+      throw new Error(`plan item ${index} matched must be a non-empty string`)
+    }
+    if (typeof item.replacement !== 'string' || item.replacement.length === 0) {
+      throw new Error(`plan item ${index} replacement must be a non-empty string`)
+    }
+    if (item.replacement === item.matched) {
+      throw new Error(`plan item ${index} replacement must differ from matched`)
+    }
+    if (typeof item.expected_line_sha256 !== 'string' || !/^[0-9a-f]{64}$/.test(item.expected_line_sha256)) {
+      throw new Error(`plan item ${index} expected_line_sha256 must be 64 lowercase hexadecimal characters`)
+    }
+  }
+  return items
+}
+
+export const assertValidPlanDocument = plan => {
+  validatePlanItems(plan?.items)
+  assertValidDocument(plan, { type: 'plan' })
+  return plan
+}
+
+export const readJsonDocument = file => {
+  let bytes
+  try {
+    bytes = fs.readFileSync(file)
+  } catch (error) {
+    throw new Error(`could not read ${file}: ${error.message}`)
+  }
+  let source
+  try {
+    source = utf8Decoder.decode(bytes)
+  } catch {
+    throw new Error(`invalid UTF-8 in ${file}`)
+  }
+  try {
+    return JSON.parse(source)
+  } catch (error) {
+    throw new Error(`invalid JSON in ${file}: ${error.message}`)
+  }
+}
+
+export const validateDocumentFile = (file, { type = null } = {}) => {
+  const document = readJsonDocument(file)
+  const result = validateDocument(document, { type, file })
+  return { ...result, document }
+}

package/lib/validate-feed.mjs

@@ -204,17 +204,23 @@ export const validateFeed = feed => {
       if (!Array.isArray(model.distributions)) {
         fail(`${at}.distributions`, 'must be an array')
       } else {
+        const seenDistributionVias = new Map()
         for (const [distributionIndex, distribution] of model.distributions.entries()) {
           const dAt = `${at}.distributions[${distributionIndex}]`
           if (!checkObjectKeys(distribution, dAt, new Set(['via', 'announced', 'shutdown', 'date_precision', 'status', 'source']))) continue
           if (!checkString(distribution.via, `${dAt}.via`, MAX_IDENTIFIER_LENGTH) || !distribution.via) fail(`${dAt}.via`, 'must be a non-empty string')
+          if (typeof distribution.via === 'string' && distribution.via.length > 0) {
+            const previous = seenDistributionVias.get(distribution.via)
+            if (previous) fail(`${dAt}.via`, `duplicate distributor via "${distribution.via}" also used at ${previous}`)
+            else seenDistributionVias.set(distribution.via, `${dAt}.via`)
+          }
           const distributionAnnounced = checkDate(distribution.announced, `${dAt}.announced`)
           const distributionShutdown = checkDate(distribution.shutdown, `${dAt}.shutdown`)
           if (distributionAnnounced && distributionShutdown && distribution.shutdown < distribution.announced) fail(dAt, 'shutdown precedes announced')
           if (distribution.date_precision !== undefined && (typeof distribution.date_precision !== 'string' || !DATE_PRECISIONS.has(distribution.date_precision))) fail(`${dAt}.date_precision`, 'must be exact or earliest')
           if (distribution.status !== undefined && (typeof distribution.status !== 'string' || !DISTRIBUTION_STATUSES.has(distribution.status))) fail(`${dAt}.status`, 'has an unsupported status')
           checkUrl(distribution.source, `${dAt}.source`)
-          if (distribution.shutdown && !(distribution.source || model.source || feed.source)) fail(dAt, 'dated distribution needs a source')
+          if ((distribution.announced || distribution.shutdown) && !(distribution.source || model.source || feed.source)) fail(dAt, 'dated distribution needs a source')
         }
       }
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "model-eol",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "AI model deprecation feeds with a zero-dependency checker, inventory CLI, and migration bot.",
   "type": "module",
   "bin": {
@@ -8,7 +8,7 @@
     "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-action-contract.mjs && node bot/test/package.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 scripts/test-document-validation.mjs && node scripts/test-eval-harness.mjs && node bot/test/package.mjs && node scripts/test-feed-changelog.mjs && node scripts/test-public-site.mjs"
   },
   "repository": {
     "type": "git",
@@ -38,12 +38,13 @@
     "bot/lib/",
     "feeds/",
     "schema/",
+    "examples/",
     "SPEC.md",
     "README.md",
     "LICENSE",
     "action.yml"
   ],
   "engines": {
-    "node": ">=20"
+    "node": ">=22"
   }
 }