model-eol 0.5.1 → 0.6.0

package/lib/reports.mjs

@@ -8,9 +8,16 @@ export const marker = status =>
   status === 'watch' ? '?' :
   '·'
 
-const shutdownText = finding => finding.date_precision === 'earliest'
-  ? `no earlier than ${finding.shutdown}`
-  : finding.shutdown
+const shutdownText = finding =>
+  finding.date_precision === 'tentative' ? `not sooner than ${finding.shutdown}` :
+  finding.date_precision === 'earliest' ? `no earlier than ${finding.shutdown}` :
+  finding.shutdown
+
+const tentativeFloor = finding => finding.date_precision === 'tentative'
+
+const policyTail = finding => finding.safe_until && finding.shutdown && finding.safe_until > finding.shutdown
+  ? `, guaranteed until ${finding.safe_until} by ${finding.publisher} policy`
+  : ''
 
 const replacementTail = finding => finding.replacement
   ? ` -> ${finding.replacement}`
@@ -18,22 +25,32 @@ const replacementTail = finding => finding.replacement
     ? ` options: ${finding.replacement_options.join(' | ')}`
     : ''
 
-export const findingTail = (f, days) =>
+const lifecycleTail = (f, days) =>
   f.status === 'retired' && !f.shutdown ? `RETIRED (shutdown date unavailable)${replacementTail(f)}` :
   f.status === 'retired' ? `RETIRED ${shutdownText(f)} (${-f.days} days ago)${replacementTail(f)}` :
   f.status === 'retiring' ? `RETIRES ${shutdownText(f)} (${f.days} days)${replacementTail(f)}` :
+  tentativeFloor(f) ? `scheduled - tentative, not announced: ${shutdownText(f)}${policyTail(f)}` :
   f.status === 'scheduled' ? `scheduled ${shutdownText(f)} (${f.days} days, outside --days ${f.threshold_days ?? days})` :
   f.status === 'watch' ? 'deprecation announced, no shutdown date yet' :
   'no retirement scheduled'
 
-const statusStyle = status =>
-  status === 'retired' ? 'red' :
-  status === 'retiring' ? 'yellow' :
-  status === 'ok' ? 'dim' :
+const waiverTail = finding => !finding.waiver
+  ? ''
+  : finding.waiver.active
+    ? `  [waived until ${finding.waiver.expires} by ${finding.waiver.owner}: ${finding.waiver.reason}]`
+    : `  [waiver expired on ${finding.waiver.expires}; owner ${finding.waiver.owner}: ${finding.waiver.reason}]`
+
+export const findingTail = (finding, days) => `${lifecycleTail(finding, days)}${waiverTail(finding)}`
+
+const statusStyle = finding =>
+  finding.waiver?.active === true ? 'yellow' :
+  finding.status === 'retired' ? 'red' :
+  finding.status === 'retiring' ? 'yellow' :
+  finding.status === 'ok' ? 'dim' :
   null
 
-const humanFinding = (status, line) => {
-  const style = statusStyle(status)
+const humanFinding = (finding, line) => {
+  const style = statusStyle(finding)
   return style ? color(style, line) : line
 }
 
@@ -67,6 +84,7 @@ export const buildInventory = ({ scan, findings, days, via, scope, targets }) =>
       replacement: lifecycle.replacement,
       ...(lifecycle.replacement_options?.length ? { replacement_options: lifecycle.replacement_options } : {}),
       ...(lifecycle.replacement_note ? { replacement_note: lifecycle.replacement_note } : {}),
+      ...(lifecycle.waiver ? { waiver: lifecycle.waiver } : {}),
       source: ref.source,
       policy: ref.policy ?? null,
       feed_generated: ref.generated ?? null,
@@ -149,9 +167,11 @@ export const buildSchedule = inventory => {
 }
 
 export const buildAlert = schedule => {
-  const errors = schedule.items.filter(item => item.status === 'retired' || item.status === 'retiring')
+  const errors = schedule.items.filter(isBad)
   const warnings = [
-    ...schedule.items.filter(item => item.status === 'scheduled' || item.status === 'watch'),
+    ...schedule.items.filter(item =>
+      item.status === 'scheduled' || item.status === 'watch' ||
+      ((item.status === 'retired' || item.status === 'retiring') && item.waiver?.active === true)),
     ...schedule.candidate_model_references.map(item => ({ ...item, status: 'unknown' })),
     ...schedule.unresolved_integrations.map(item => ({ ...item, status: 'unresolved' })),
   ]
@@ -174,7 +194,7 @@ export const formatCheck = ({ findings, bad, scannedFiles, days, scope }) => {
   }
   for (const f of findings) {
     const where = `${f.file}:${f.line}`
-    out.push(humanFinding(f.status, `${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}]` : ''}`))
   }
   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')
@@ -187,7 +207,7 @@ export const formatInventory = (inventory, days) => {
   if (inventory.model_references.length) {
     out.push('\nModel references')
     for (const item of inventory.model_references) {
-      out.push(humanFinding(item.status, `${marker(item.status)} ${item.file}:${item.line}  ${item.matched}  ${item.publisher}/${item.id}  ${item.usage}  ${findingTail(item, days)}`))
+      out.push(humanFinding(item, `${marker(item.status)} ${item.file}:${item.line}  ${item.matched}  ${item.publisher}/${item.id}  ${item.usage}  ${findingTail(item, days)}`))
     }
   }
   if (inventory.candidate_model_references.length) {
@@ -212,7 +232,7 @@ export const formatSchedule = (schedule, days) => {
   if (incompleteNotes.length) out.push(`WARNING: scan incomplete; ${incompleteNotes.length} coverage-loss note(s) recorded`)
   for (const item of schedule.items) {
     const safeUntil = item.safe_until ? `  [safe until ${item.safe_until}]` : ''
-    out.push(humanFinding(item.status, `${marker(item.status)} ${item.shutdown ? shutdownText(item) : 'TBD'}  ${item.file}:${item.line}  ${item.matched}  ${findingTail(item, days)}  [${item.usage}]${safeUntil}`))
+    out.push(humanFinding(item, `${marker(item.status)} ${item.shutdown ? shutdownText(item) : 'TBD'}  ${item.file}:${item.line}  ${item.matched}  ${findingTail(item, days)}  [${item.usage}]${safeUntil}`))
   }
   if (schedule.unresolved_integrations.length) {
     out.push('\nUnresolved cloud/gateway references')
@@ -279,6 +299,7 @@ export const formatInventoryCycloneDX = inventory => {
         identity,
         item,
         status: item.status,
+        occurrenceWaivers: new Map(),
         usages: new Set(),
         occurrences: new Set(),
       }
@@ -287,12 +308,54 @@ export const formatInventoryCycloneDX = inventory => {
     if ((statusSeverity.get(item.status) ?? 9) < (statusSeverity.get(group.status) ?? 9)) {
       group.status = item.status
     }
+    const location = `${item.file}#${item.line}`
+    const occurrenceWaiver = group.occurrenceWaivers.get(location) ?? { active: true, activeWaivers: [], expiredWaivers: [] }
+    if (item.waiver?.active === true) occurrenceWaiver.activeWaivers.push(item.waiver)
+    else {
+      occurrenceWaiver.active = false
+      if (item.waiver?.active === false) occurrenceWaiver.expiredWaivers.push(item.waiver)
+    }
+    group.occurrenceWaivers.set(location, occurrenceWaiver)
     group.usages.add(item.usage)
-    group.occurrences.add(`${item.file}#${item.line}`)
+    group.occurrences.add(location)
   }
 
   const components = [...groups.values()].map(group => {
     const { item, identity } = group
+    const occurrenceWaivers = [...group.occurrenceWaivers.values()]
+    const activeWaivers = occurrenceWaivers.flatMap(occurrence => occurrence.activeWaivers)
+    const expiredWaivers = occurrenceWaivers.flatMap(occurrence => occurrence.expiredWaivers)
+    const everyOccurrenceWaived = occurrenceWaivers.every(occurrence => occurrence.active && occurrence.activeWaivers.length > 0)
+    let waiverProperties = []
+    if (activeWaivers.length > 0 && !everyOccurrenceWaived) {
+      waiverProperties = [{ name: 'model-eol:waiver_active', value: 'partial' }]
+    } else if (everyOccurrenceWaived) {
+      const earliestExpiry = activeWaivers.map(waiver => waiver.expires).sort()[0]
+      const distinctWaivers = new Set(activeWaivers.map(waiver => JSON.stringify([waiver.owner, waiver.expires, waiver.reason])))
+      waiverProperties = [
+        { name: 'model-eol:waiver_active', value: 'true' },
+        ...(distinctWaivers.size === 1
+          ? [
+              { name: 'model-eol:waiver_owner', value: activeWaivers[0].owner },
+              { name: 'model-eol:waiver_expires', value: earliestExpiry },
+              { name: 'model-eol:waiver_reason', value: activeWaivers[0].reason },
+            ]
+          : [{ name: 'model-eol:waiver_expires', value: earliestExpiry }]),
+      ]
+    } else if (expiredWaivers.length > 0) {
+      const latestExpiry = expiredWaivers.map(waiver => waiver.expires).sort().at(-1)
+      const distinctWaivers = new Set(expiredWaivers.map(waiver => JSON.stringify([waiver.owner, waiver.expires, waiver.reason])))
+      waiverProperties = [
+        { name: 'model-eol:waiver_active', value: 'false' },
+        ...(distinctWaivers.size === 1
+          ? [
+              { name: 'model-eol:waiver_owner', value: expiredWaivers[0].owner },
+              { name: 'model-eol:waiver_expires', value: latestExpiry },
+              { name: 'model-eol:waiver_reason', value: expiredWaivers[0].reason },
+            ]
+          : [{ name: 'model-eol:waiver_expires', value: latestExpiry }]),
+      ]
+    }
     return {
       type: 'machine-learning-model',
       'bom-ref': identity.bomRef,
@@ -319,6 +382,7 @@ export const formatInventoryCycloneDX = inventory => {
         ...(item.replacement_note
           ? [{ name: 'model-eol:replacement_note', value: item.replacement_note }]
           : []),
+        ...waiverProperties,
         { name: 'model-eol:usage', value: [...group.usages].sort().join(',') },
       ],
       evidence: {

package/lib/scanner.mjs

@@ -638,6 +638,7 @@ export const scanTargets = ({
 
   const pushModelRef = ({ file, line, lineText, matchIndex = null, matched, record, classification, route = null, mappedFrom = null }) => {
     if (ignoresModel(file, matched, record.entry.id) || (mappedFrom && ignoresModel(file, mappedFrom, record.entry.id))) return
+    const waivers = policyForFile?.(path.resolve(file))?.waivers ?? []
     const occurrence = [...lineText.matchAll(new RegExp(escapeRegExp(matched), 'g'))]
       .findIndex(match => match.index === (matchIndex ?? lineText.indexOf(matched)))
     modelRefs.push({
@@ -659,6 +660,7 @@ export const scanTargets = ({
       occurrence: occurrence < 0 ? 0 : occurrence,
       route_index: route?.index ?? null,
       mapped_from: mappedFrom,
+      waivers,
     })
   }
 

package/lib/validate-document.mjs

@@ -64,7 +64,7 @@ export const normalizeDocumentType = value => {
 const isObject = value => value !== null && typeof value === 'object' && !Array.isArray(value)
 
 const configKeys = new Set([
-  'days', 'scope', 'via', 'feeds', 'ignore', 'overrides', 'routes', 'issues', 'eval',
+  'days', 'scope', 'via', 'feeds', 'ignore', 'waivers', 'overrides', 'routes', 'issues', 'eval',
 ])
 
 export const detectDocumentType = (document, { file = null } = {}) => {

package/lib/validate-feed.mjs

@@ -9,8 +9,9 @@ export const MAX_TIMEOUT_MS = 3600000
 const CONTROL_CHARACTER_PATTERN = /[\u0000-\u001f\u007f-\u009f]/
 const DATE_PATTERN = /^\d{4}-\d{2}-\d{2}$/
 const DATE_TIME_PATTERN = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})$/
-const DATE_PRECISIONS = new Set(['exact', 'earliest'])
+const DATE_PRECISIONS = new Set(['exact', 'earliest', 'tentative'])
 const DISTRIBUTION_STATUSES = new Set(['active', 'legacy', 'extended-access', 'retired'])
+const RESERVED_DISTRIBUTION_VIAS = new Set(['publisher', 'publisher-fallback'])
 
 export const assertIsoDate = (value, label = 'date') => {
   if (typeof value !== 'string' || !DATE_PATTERN.test(value)) {
@@ -181,7 +182,13 @@ export const validateFeed = feed => {
     const shutdownValid = checkDate(model.shutdown, `${at}.shutdown`)
     if (announcedValid && shutdownValid) validDates.push({ at, announced: model.announced, shutdown: model.shutdown })
     if (model.date_precision !== undefined) {
-      if (typeof model.date_precision !== 'string' || !DATE_PRECISIONS.has(model.date_precision)) fail(`${at}.date_precision`, 'must be exact or earliest')
+      if (typeof model.date_precision !== 'string' || !DATE_PRECISIONS.has(model.date_precision)) fail(`${at}.date_precision`, 'must be exact, earliest, or tentative')
+    }
+    if (model.date_precision === 'tentative' && model.announced !== undefined) {
+      fail(`${at}.announced`, 'must be absent when date_precision is tentative')
+    }
+    if (model.date_precision === 'tentative' && model.shutdown === undefined) {
+      fail(`${at}.shutdown`, 'is required when date_precision is tentative')
     }
     if (model.replacement !== undefined) checkIdentifier(model.replacement, `${at}.replacement`)
     if (model.replacement_options !== undefined) {
@@ -210,6 +217,9 @@ export const validateFeed = feed => {
           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) {
+            if (RESERVED_DISTRIBUTION_VIAS.has(distribution.via.toLowerCase())) {
+              fail(`${dAt}.via`, 'must not use a reserved publisher clock name')
+            }
             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`)
@@ -217,8 +227,17 @@ export const validateFeed = feed => {
           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.date_precision !== undefined && (typeof distribution.date_precision !== 'string' || !DATE_PRECISIONS.has(distribution.date_precision))) fail(`${dAt}.date_precision`, 'must be exact, earliest, or tentative')
           if (distribution.status !== undefined && (typeof distribution.status !== 'string' || !DISTRIBUTION_STATUSES.has(distribution.status))) fail(`${dAt}.status`, 'has an unsupported status')
+          if (distribution.date_precision === 'tentative' && distribution.announced !== undefined) {
+            fail(`${dAt}.announced`, 'must be absent when date_precision is tentative')
+          }
+          if (distribution.date_precision === 'tentative' && distribution.shutdown === undefined) {
+            fail(`${dAt}.shutdown`, 'is required when date_precision is tentative')
+          }
+          if (distribution.date_precision === 'tentative' && distribution.status === 'retired') {
+            fail(`${dAt}.status`, 'must not be retired when date_precision is tentative')
+          }
           checkUrl(distribution.source, `${dAt}.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.5.1",
+  "version": "0.6.0",
   "description": "AI model deprecation feeds with a zero-dependency checker, inventory CLI, and migration bot.",
   "type": "module",
   "bin": {

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

@@ -54,6 +54,13 @@
       },
       "default": { "models": [], "paths": [] }
     },
+    "waivers": {
+      "type": "array",
+      "maxItems": 500,
+      "items": { "$ref": "#/definitions/waiver" },
+      "default": [],
+      "description": "Owned, expiring exceptions that remain visible in reports while active."
+    },
     "overrides": {
       "type": "array",
       "items": { "$ref": "#/definitions/pathOverride" },
@@ -120,6 +127,7 @@
     "via": null,
     "feeds": { "allow_vendored_fallback": false },
     "ignore": { "models": [], "paths": [] },
+    "waivers": [],
     "overrides": [],
     "routes": [],
     "issues": { "enabled": true },
@@ -144,6 +152,24 @@
         "paths": { "$ref": "#/definitions/stringArray" }
       }
     },
+    "waiver": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["model", "reason", "owner", "expires"],
+      "properties": {
+        "model": { "type": "string", "minLength": 1 },
+        "paths": { "$ref": "#/definitions/stringArray" },
+        "via": { "type": "string", "minLength": 1 },
+        "reason": { "type": "string", "minLength": 1, "maxLength": 500 },
+        "owner": { "type": "string", "minLength": 1, "maxLength": 200 },
+        "expires": { "type": "string", "format": "date" }
+      }
+    },
+    "waivers": {
+      "type": "array",
+      "maxItems": 500,
+      "items": { "$ref": "#/definitions/waiver" }
+    },
     "pathOverride": {
       "type": "object",
       "additionalProperties": false,
@@ -153,7 +179,8 @@
         "days": { "type": "integer", "minimum": 0 },
         "scope": { "enum": ["direct", "all"] },
         "via": { "type": ["string", "null"], "minLength": 1 },
-        "ignore": { "$ref": "#/definitions/ignore" }
+        "ignore": { "$ref": "#/definitions/ignore" },
+        "waivers": { "$ref": "#/definitions/waivers" }
       }
     },
     "referenceRoute": {

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

@@ -32,7 +32,7 @@
         "confidence": { "$ref": "https://thossullivan.github.io/model-eol/schema/0.1/model-eol.inventory.schema.json#/definitions/confidence" },
         "status": { "$ref": "https://thossullivan.github.io/model-eol/schema/0.1/model-eol.inventory.schema.json#/definitions/status" },
         "shutdown": { "type": ["string", "null"], "format": "date" },
-        "date_precision": { "enum": ["exact", "earliest", null] },
+        "date_precision": { "enum": ["exact", "earliest", "tentative", null] },
         "distribution_status": { "enum": ["active", "legacy", "extended-access", "retired", null] },
         "via": { "type": ["string", "null"], "minLength": 1 },
         "days": { "type": ["integer", "null"] },
@@ -47,6 +47,7 @@
         "threshold_days": { "type": "integer", "minimum": 0 },
         "effective_scope": { "enum": ["all", "direct"] },
         "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 }
       },

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

@@ -60,7 +60,7 @@
         "evidence": { "type": "string", "minLength": 1 },
         "status": { "$ref": "#/definitions/status" },
         "shutdown": { "type": ["string", "null"], "format": "date" },
-        "date_precision": { "enum": ["exact", "earliest", null] },
+        "date_precision": { "enum": ["exact", "earliest", "tentative", null] },
         "distribution_status": { "enum": ["active", "legacy", "extended-access", "retired", null] },
         "via": { "type": ["string", "null"], "minLength": 1 },
         "requested_via": { "type": ["string", "null"], "minLength": 1 },
@@ -77,6 +77,7 @@
           "items": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]*$" }
         },
         "replacement_note": { "type": "string", "minLength": 1 },
+        "waiver": { "$ref": "#/definitions/waiver" },
         "source": { "type": ["string", "null"], "format": "uri" },
         "policy": {
           "type": ["object", "null"],
@@ -147,6 +148,17 @@
         "route_index": { "type": ["integer", "null"], "minimum": 0 }
       },
       "additionalProperties": false
+    },
+    "waiver": {
+      "type": ["object", "null"],
+      "required": ["reason", "owner", "expires", "active"],
+      "properties": {
+        "reason": { "type": "string", "minLength": 1, "maxLength": 500 },
+        "owner": { "type": "string", "minLength": 1, "maxLength": 200 },
+        "expires": { "type": "string", "format": "date" },
+        "active": { "type": "boolean" }
+      },
+      "additionalProperties": false
     }
   }
 }

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

@@ -36,6 +36,7 @@
         "effective_scope": { "enum": ["all", "direct"] },
         "policy_provenance": { "$ref": "#/definitions/policyProvenance" },
         "mapped_from": { "type": "string", "minLength": 1 },
+        "waiver": { "$ref": "#/definitions/waiver" },
         "sources": { "type": "array", "items": { "type": "string" } },
         "notes": { "type": ["string", "null"] }
       },
@@ -69,6 +70,7 @@
         },
         "replacement_note": { "type": "string" },
         "provider": { "type": "string" },
+        "waiver": { "$ref": "#/definitions/waiver" },
         "reason": { "type": "string", "minLength": 1 },
         "sources": { "type": "array", "items": { "type": "string" } },
         "notes": { "type": ["string", "null"] }
@@ -99,6 +101,17 @@
         "route_index": { "type": ["integer", "null"], "minimum": 0 }
       },
       "additionalProperties": false
+    },
+    "waiver": {
+      "type": ["object", "null"],
+      "required": ["reason", "owner", "expires", "active"],
+      "properties": {
+        "reason": { "type": "string", "minLength": 1, "maxLength": 500 },
+        "owner": { "type": "string", "minLength": 1, "maxLength": 200 },
+        "expires": { "type": "string", "format": "date" },
+        "active": { "type": "boolean" }
+      },
+      "additionalProperties": false
     }
   }
 }

package/schema/model-eol.schema.json

@@ -40,7 +40,7 @@
         },
         "announced": { "$ref": "#/definitions/isoDate" },
         "shutdown": { "$ref": "#/definitions/isoDate" },
-        "date_precision": { "enum": ["exact", "earliest"] },
+        "date_precision": { "enum": ["exact", "earliest", "tentative"] },
         "replacement": { "type": "string", "maxLength": 256, "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]*$" },
         "replacement_options": {
           "type": "array",
@@ -59,7 +59,7 @@
               "via": { "type": "string", "minLength": 1 },
               "announced": { "$ref": "#/definitions/isoDate" },
               "shutdown": { "$ref": "#/definitions/isoDate" },
-              "date_precision": { "enum": ["exact", "earliest"] },
+              "date_precision": { "enum": ["exact", "earliest", "tentative"] },
               "status": { "enum": ["active", "legacy", "extended-access", "retired"] },
               "source": { "type": "string", "format": "uri" }
             },