modelalive 0.5.0 → 1.2.0

package/dist/alive.d.ts

@@ -0,0 +1,2 @@
+import type { AliveResult } from "./types.js";
+export declare function alive(model: string, today?: Date): AliveResult;

package/dist/alive.js

@@ -0,0 +1,54 @@
+import { daysUntil, effectiveStatus, loadRegistry, resolveAlias, } from "./registry.js";
+import { normalizeModel } from "./normalize.js";
+export function alive(model, today = new Date()) {
+    const registry = loadRegistry();
+    const queried = normalizeModel(model);
+    const [canonical, aliased] = resolveAlias(queried, registry);
+    const entry = registry.models[canonical];
+    if (!entry) {
+        return {
+            model: canonical,
+            queried_model: queried,
+            canonical_model: canonical,
+            aliased,
+            alive: true,
+            status: "unknown",
+            confidence: "unknown",
+            message: "Model not in registry — assumed alive.",
+            registry_version: registry.version,
+        };
+    }
+    const status = effectiveStatus(entry, today);
+    const sourceKey = entry.source ?? "";
+    const sourceMeta = registry.sources[sourceKey];
+    const daysLeft = daysUntil(entry.retired_at, today);
+    const base = {
+        model: canonical,
+        queried_model: queried,
+        canonical_model: canonical,
+        aliased,
+        provider: entry.provider,
+        deprecated_at: entry.deprecated_at,
+        retired_at: entry.retired_at,
+        replacement: entry.replacement ?? null,
+        breaking_changes: entry.breaking_changes ?? [],
+        migrate_url: entry.migrate_url,
+        days_until_retirement: daysLeft,
+        registry_version: registry.version,
+        source_url: sourceMeta?.url,
+        source_checked_at: sourceMeta?.checked_at,
+        confidence: entry.source ? "verified" : "unknown",
+        alive: status !== "retired",
+        status: status,
+    };
+    if (status === "retired") {
+        const repl = entry.replacement ? ` Use '${entry.replacement}' instead.` : "";
+        base.message = `Model '${canonical}' was retired.${repl}`;
+        base.alive = false;
+    }
+    else if (status === "deprecated") {
+        base.message = `Model '${canonical}' is deprecated.`;
+        base.alive = true;
+    }
+    return base;
+}

package/dist/expiring.d.ts

@@ -0,0 +1,6 @@
+import type { AliveResult } from "./types.js";
+export declare function listExpiring(opts?: {
+    withinDays?: number;
+    provider?: string;
+    today?: Date;
+}): AliveResult[];

package/dist/expiring.js

@@ -0,0 +1,26 @@
+import { alive } from "./alive.js";
+import { effectiveStatus, loadRegistry, parseDate } from "./registry.js";
+export function listExpiring(opts = {}) {
+    const withinDays = opts.withinDays ?? 30;
+    const today = opts.today ?? new Date();
+    const registry = loadRegistry();
+    const results = [];
+    for (const [modelId, entry] of Object.entries(registry.models)) {
+        if (opts.provider && entry.provider !== opts.provider)
+            continue;
+        const status = effectiveStatus(entry, today);
+        if (status !== "deprecated" && status !== "retired")
+            continue;
+        const retiredAt = parseDate(entry.retired_at);
+        if (!retiredAt)
+            continue;
+        const ms = retiredAt.getTime() - today.getTime();
+        const daysLeft = Math.floor(ms / (1000 * 60 * 60 * 24));
+        if (status === "retired" || daysLeft < 0)
+            continue;
+        if (daysLeft <= withinDays) {
+            results.push(alive(modelId, today));
+        }
+    }
+    return results.sort((a, b) => (a.days_until_retirement ?? 9999) - (b.days_until_retirement ?? 9999));
+}

package/dist/index.d.ts

@@ -1,12 +1,21 @@
-import type { AliveResult } from "./types.js";
-export declare function alive(model: string, today?: Date): AliveResult;
-export declare function check(model: string, opts?: {
-    strictUnknown?: boolean;
-    today?: Date;
-}): AliveResult;
+import type { AliveResult, CheckOptions } from "./types.js";
+export { alive } from "./alive.js";
+export declare function check(model: string, opts?: CheckOptions): AliveResult;
+export declare function checkMany(models: string[], today?: Date): AliveResult[];
 export declare function resolve(model: string, today?: Date): string;
-export declare function ensure(model: string, opts?: {
-    strictUnknown?: boolean;
-    today?: Date;
-}): string;
+export interface ResolveDetail {
+    queried_model: string;
+    resolved: string;
+    chain: string[];
+    breaking_changes: string[];
+}
+export declare function resolveDetail(model: string, today?: Date): ResolveDetail;
+export declare function ensure(model: string, opts?: CheckOptions): string;
+export declare function requireAlive(model: string, opts?: CheckOptions): string;
+export declare function gate<T>(model: string, fn: (safeModel: string) => T, opts?: CheckOptions): T;
 export * from "./types.js";
+export { normalizeModel } from "./normalize.js";
+export { listExpiring } from "./expiring.js";
+export { scanPath } from "./scan.js";
+export type { ScanFinding, ScanReport } from "./scan.js";
+export { defaultStrictUnknown, defaultWarnDays, defaultWarnDeprecated, } from "./settings.js";

package/dist/index.js

@@ -1,95 +1,125 @@
-import { daysUntil, effectiveStatus, loadRegistry, resolveAlias, } from "./registry.js";
-import { ModelRetiredError, ModelUnknownError } from "./types.js";
-export function alive(model, today = new Date()) {
-    const registry = loadRegistry();
-    const queried = model.trim();
-    const [canonical, aliased] = resolveAlias(queried, registry);
-    const entry = registry.models[canonical];
-    if (!entry) {
-        return {
-            model: canonical,
-            queried_model: queried,
-            canonical_model: canonical,
-            aliased,
-            alive: true,
-            status: "unknown",
-            confidence: "unknown",
-            message: "Model not in registry — assumed alive.",
-            registry_version: registry.version,
-        };
-    }
-    const status = effectiveStatus(entry, today);
-    const sourceKey = entry.source ?? "";
-    const sourceMeta = registry.sources[sourceKey];
-    const daysLeft = daysUntil(entry.retired_at, today);
-    const base = {
-        model: canonical,
-        queried_model: queried,
-        canonical_model: canonical,
-        aliased,
-        provider: entry.provider,
-        deprecated_at: entry.deprecated_at,
-        retired_at: entry.retired_at,
-        replacement: entry.replacement ?? null,
-        breaking_changes: entry.breaking_changes ?? [],
-        migrate_url: entry.migrate_url,
-        days_until_retirement: daysLeft,
-        registry_version: registry.version,
-        source_url: sourceMeta?.url,
-        source_checked_at: sourceMeta?.checked_at,
-        confidence: entry.source ? "verified" : "unknown",
-        alive: status !== "retired",
-        status: status,
-    };
-    if (status === "retired") {
-        const repl = entry.replacement ? ` Use '${entry.replacement}' instead.` : "";
-        base.message = `Model '${canonical}' was retired.${repl}`;
-        base.alive = false;
-    }
-    else if (status === "deprecated") {
-        base.message = `Model '${canonical}' is deprecated.`;
-        base.alive = true;
-    }
-    return base;
-}
+import { alive } from "./alive.js";
+import { normalizeModel } from "./normalize.js";
+import { defaultStrictUnknown, defaultWarnDays, defaultWarnDeprecated, } from "./settings.js";
+import { ModelDeprecatedError, ModelExpiringSoonError, ModelRetiredError, ModelUnknownError, } from "./types.js";
+const MAX_DEPTH = 12;
+export { alive } from "./alive.js";
 export function check(model, opts = {}) {
-    const result = alive(model, opts.today);
-    if (opts.strictUnknown && result.status === "unknown") {
+    const strictUnknown = opts.strictUnknown ?? defaultStrictUnknown();
+    const warnDeprecated = opts.warnDeprecated ?? defaultWarnDeprecated();
+    const warnDays = opts.warnDays ?? defaultWarnDays();
+    const today = opts.today;
+    const result = alive(model, today);
+    if (strictUnknown && result.status === "unknown") {
         throw new ModelUnknownError(result);
     }
     if (result.status === "retired") {
         throw new ModelRetiredError(result);
     }
+    if (warnDeprecated && result.status === "deprecated") {
+        throw new ModelDeprecatedError(result);
+    }
+    if (warnDays != null &&
+        result.status === "deprecated" &&
+        result.days_until_retirement != null &&
+        result.days_until_retirement >= 0 &&
+        result.days_until_retirement <= warnDays) {
+        throw new ModelExpiringSoonError(result);
+    }
     return result;
 }
+export function checkMany(models, today = new Date()) {
+    return models.map((m) => alive(m, today));
+}
 export function resolve(model, today = new Date()) {
-    let current = model.trim();
+    return resolveDetail(model, today).resolved;
+}
+export function resolveDetail(model, today = new Date()) {
+    let current = normalizeModel(model);
     const visited = new Set();
-    for (let i = 0; i < 12; i++) {
+    const chain = [];
+    const breakingChanges = [];
+    for (let i = 0; i < MAX_DEPTH; i++) {
         if (visited.has(current))
             break;
         visited.add(current);
+        chain.push(current);
         const result = alive(current, today);
+        for (const change of result.breaking_changes ?? []) {
+            if (!breakingChanges.includes(change))
+                breakingChanges.push(change);
+        }
         if (result.status === "active" || result.status === "unknown") {
-            return result.canonical_model ?? current;
+            return {
+                queried_model: model,
+                resolved: result.canonical_model ?? current,
+                chain,
+                breaking_changes: breakingChanges,
+            };
+        }
+        if (!result.replacement) {
+            return {
+                queried_model: model,
+                resolved: result.canonical_model ?? current,
+                chain,
+                breaking_changes: breakingChanges,
+            };
         }
-        if (!result.replacement)
-            return result.canonical_model ?? current;
         const repl = alive(result.replacement, today);
-        if (repl.status === "active")
-            return result.replacement;
+        if (repl.status === "active") {
+            for (const change of repl.breaking_changes ?? []) {
+                if (!breakingChanges.includes(change))
+                    breakingChanges.push(change);
+            }
+            return {
+                queried_model: model,
+                resolved: result.replacement,
+                chain: [...chain, result.replacement],
+                breaking_changes: breakingChanges,
+            };
+        }
         current = result.replacement;
     }
-    return current;
+    return {
+        queried_model: model,
+        resolved: current,
+        chain,
+        breaking_changes: breakingChanges,
+    };
 }
 export function ensure(model, opts = {}) {
-    const result = alive(model, opts.today);
-    if (opts.strictUnknown && result.status === "unknown") {
+    const strictUnknown = opts.strictUnknown ?? defaultStrictUnknown();
+    const warnDeprecated = opts.warnDeprecated ?? defaultWarnDeprecated();
+    const warnDays = opts.warnDays ?? defaultWarnDays();
+    const today = opts.today;
+    const result = alive(model, today);
+    if (strictUnknown && result.status === "unknown") {
         throw new ModelUnknownError(result);
     }
     if (result.status === "retired" && !result.replacement) {
         throw new ModelRetiredError(result);
     }
-    return resolve(model, opts.today);
+    if (warnDeprecated && result.status === "deprecated") {
+        throw new ModelDeprecatedError(result);
+    }
+    if (warnDays != null &&
+        result.status === "deprecated" &&
+        result.days_until_retirement != null &&
+        result.days_until_retirement >= 0 &&
+        result.days_until_retirement <= warnDays) {
+        throw new ModelExpiringSoonError(result);
+    }
+    return resolve(model, today);
+}
+export function requireAlive(model, opts = {}) {
+    check(model, opts);
+    return model;
+}
+export function gate(model, fn, opts = {}) {
+    return fn(ensure(model, opts));
 }
 export * from "./types.js";
+export { normalizeModel } from "./normalize.js";
+export { listExpiring } from "./expiring.js";
+export { scanPath } from "./scan.js";
+export { defaultStrictUnknown, defaultWarnDays, defaultWarnDeprecated, } from "./settings.js";

package/dist/normalize.d.ts

@@ -0,0 +1 @@
+export declare function normalizeModel(model: string): string;

package/dist/normalize.js

@@ -0,0 +1,17 @@
+const MODEL_ID_PATTERN = /^[a-zA-Z0-9][a-zA-Z0-9._:/-]{0,200}$/;
+const FINE_TUNED_PREFIX = /^ft:([^:]+(?::[^:]+)*)/;
+export function normalizeModel(model) {
+    let cleaned = model.trim();
+    if (!cleaned)
+        throw new Error("Model ID cannot be empty");
+    const ftMatch = FINE_TUNED_PREFIX.exec(cleaned);
+    if (ftMatch) {
+        const base = ftMatch[1].split(":")[0];
+        if (base)
+            cleaned = base;
+    }
+    if (!MODEL_ID_PATTERN.test(cleaned)) {
+        throw new Error(`Invalid model ID format: ${model}`);
+    }
+    return cleaned;
+}

package/dist/parity.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/parity.test.js

@@ -0,0 +1,42 @@
+import assert from "node:assert/strict";
+import { alive, check, checkMany, defaultStrictUnknown, ensure, gate, listExpiring, normalizeModel, resolve, resolveDetail, scanPath, } from "./index.js";
+import { mkdtempSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { ModelRetiredError, ModelUnknownError, } from "./types.js";
+// Core lifecycle
+assert.equal(alive("claude-sonnet-4-20250514").status, "retired");
+assert.equal(resolve("claude-sonnet-4-20250514"), "claude-sonnet-4-6");
+assert.equal(ensure("claude-sonnet-4-20250514"), "claude-sonnet-4-6");
+assert.equal(alive("claude-sonnet-4-6").status, "active");
+const detail = resolveDetail("claude-opus-4-20250514");
+assert.equal(detail.resolved, "claude-opus-4-8");
+assert.ok(detail.breaking_changes.length >= 1);
+assert.equal(normalizeModel("ft:gpt-4o-mini:org:foo:bar"), "gpt-4o-mini");
+// Bedrock host entry
+const bedrock = alive("anthropic.claude-sonnet-4-6-v1:0");
+assert.equal(bedrock.provider, "bedrock");
+assert.equal(bedrock.status, "active");
+// Azure host entry
+const azure = alive("azure/gpt-4o");
+assert.equal(azure.provider, "azure");
+// OpenRouter crosswalk
+assert.equal(resolve("anthropic/claude-sonnet-4-6"), "claude-sonnet-4-6");
+const gated = gate("gemini-2.0-flash", (safe) => safe);
+assert.equal(gated, "gemini-3.5-flash");
+// checkMany
+assert.equal(checkMany(["gpt-4o", "claude-sonnet-4-6"]).length, 2);
+// listExpiring
+const expiring = listExpiring({ withinDays: 365, provider: "anthropic" });
+assert.ok(Array.isArray(expiring));
+// scanPath
+const dir = mkdtempSync(join(tmpdir(), "modelalive-"));
+writeFileSync(join(dir, "app.py"), 'MODEL = "claude-sonnet-4-20250514"\n');
+const scan = scanPath(dir);
+assert.ok(scan.findings.length >= 1);
+// Errors
+assert.throws(() => check("totally-unknown-model-xyz", { strictUnknown: true }), ModelUnknownError);
+assert.throws(() => check("claude-sonnet-4-20250514"), ModelRetiredError);
+// env defaults (undefined when unset in test env)
+assert.equal(typeof defaultStrictUnknown(), "boolean");
+console.log("modelalive js parity: ok");

package/dist/scan.d.ts

@@ -0,0 +1,14 @@
+export interface ScanFinding {
+    path: string;
+    line: number;
+    model: string;
+    status: string;
+    replacement?: string | null;
+    alive: boolean;
+}
+export interface ScanReport {
+    root: string;
+    scannedFiles: number;
+    findings: ScanFinding[];
+}
+export declare function scanPath(root: string, today?: Date): ScanReport;

package/dist/scan.js

@@ -0,0 +1,111 @@
+import { alive } from "./alive.js";
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+const SKIP_DIRS = new Set([
+    ".git",
+    ".venv",
+    "venv",
+    "node_modules",
+    "__pycache__",
+    ".pytest_cache",
+    "dist",
+    "build",
+    ".eggs",
+]);
+const EXTENSIONS = new Set([
+    ".py",
+    ".ts",
+    ".tsx",
+    ".js",
+    ".jsx",
+    ".json",
+    ".yaml",
+    ".yml",
+    ".toml",
+    ".env",
+    ".md",
+    ".sh",
+]);
+const PATTERNS = [
+    /['"](claude-[a-zA-Z0-9._-]{3,128})['"]/g,
+    /['"](gpt-[a-zA-Z0-9._-]{3,128})['"]/g,
+    /['"](gemini-[a-zA-Z0-9._-]{3,128})['"]/g,
+    /['"](o[0-9]-[a-zA-Z0-9._-]{3,128})['"]/g,
+    /['"](llama-[a-zA-Z0-9._-]{3,128})['"]/g,
+    /['"](grok-[a-zA-Z0-9._-]{3,128})['"]/g,
+    /['"](deepseek-[a-zA-Z0-9._-]{3,128})['"]/g,
+    /['"](mistral-[a-zA-Z0-9._-]{3,128})['"]/g,
+    /['"](qwen[a-zA-Z0-9._-]{0,128})['"]/g,
+    /['"](anthropic\.claude-[a-zA-Z0-9._:-]{3,128})['"]/g,
+    /['"]((?:anthropic|openai|google|meta-llama|qwen|deepseek|mistral|x-ai)\/[a-zA-Z0-9._:-]{3,128})['"]/g,
+    /model\s*[=:]\s*['"]([a-zA-Z0-9][a-zA-Z0-9._:/-]{2,127})['"]/g,
+];
+function walk(dir, files = []) {
+    for (const name of readdirSync(dir)) {
+        const path = join(dir, name);
+        const parts = path.split(/[/\\]/);
+        if (parts.some((p) => SKIP_DIRS.has(p)))
+            continue;
+        const st = statSync(path);
+        if (st.isDirectory())
+            walk(path, files);
+        else
+            files.push(path);
+    }
+    return files;
+}
+function shouldScan(path) {
+    if (path.endsWith(".min.js") || path.endsWith(".map"))
+        return false;
+    const ext = path.slice(path.lastIndexOf("."));
+    return EXTENSIONS.has(ext) || path.endsWith("Dockerfile") || path.endsWith(".env");
+}
+export function scanPath(root, today = new Date()) {
+    const report = { root, scannedFiles: 0, findings: [] };
+    const seen = new Set();
+    for (const path of walk(root)) {
+        if (!shouldScan(path))
+            continue;
+        let text;
+        try {
+            text = readFileSync(path, "utf-8");
+        }
+        catch {
+            continue;
+        }
+        report.scannedFiles += 1;
+        const lines = text.split(/\r?\n/);
+        for (let i = 0; i < lines.length; i++) {
+            const line = lines[i];
+            for (const pattern of PATTERNS) {
+                pattern.lastIndex = 0;
+                let match;
+                while ((match = pattern.exec(line)) !== null) {
+                    const model = match[1];
+                    const key = `${path}:${i + 1}:${model}`;
+                    if (seen.has(key))
+                        continue;
+                    seen.add(key);
+                    let result;
+                    try {
+                        result = alive(model, today);
+                    }
+                    catch {
+                        continue;
+                    }
+                    if (result.status === "active")
+                        continue;
+                    report.findings.push({
+                        path: path.startsWith(root) ? path.slice(root.length + 1) : path,
+                        line: i + 1,
+                        model,
+                        status: result.status,
+                        replacement: result.replacement,
+                        alive: result.alive,
+                    });
+                }
+            }
+        }
+    }
+    return report;
+}

package/dist/settings.d.ts

@@ -0,0 +1,5 @@
+/** Environment-driven defaults (parity with Python MODELALIVE_*). */
+export declare function envFlag(name: string, defaultValue?: boolean): boolean;
+export declare function defaultStrictUnknown(): boolean;
+export declare function defaultWarnDeprecated(): boolean;
+export declare function defaultWarnDays(): number | undefined;

package/dist/settings.js

@@ -0,0 +1,20 @@
+/** Environment-driven defaults (parity with Python MODELALIVE_*). */
+export function envFlag(name, defaultValue = false) {
+    const raw = (process.env[name] ?? "").trim().toLowerCase();
+    if (!raw)
+        return defaultValue;
+    return ["1", "true", "yes", "on"].includes(raw);
+}
+export function defaultStrictUnknown() {
+    return envFlag("MODELALIVE_STRICT");
+}
+export function defaultWarnDeprecated() {
+    return envFlag("MODELALIVE_WARN_DEPRECATED");
+}
+export function defaultWarnDays() {
+    const raw = (process.env["MODELALIVE_WARN_DAYS"] ?? "").trim();
+    if (!raw)
+        return undefined;
+    const n = Number.parseInt(raw, 10);
+    return Number.isFinite(n) && n >= 0 ? n : undefined;
+}

package/dist/smoke.test.js

@@ -1,7 +1,14 @@
 import assert from "node:assert/strict";
-import { alive, ensure, resolve } from "./index.js";
+import { alive, ensure, gate, normalizeModel, resolve, resolveDetail, } from "./index.js";
 assert.equal(alive("claude-sonnet-4-20250514").status, "retired");
 assert.equal(resolve("claude-sonnet-4-20250514"), "claude-sonnet-4-6");
 assert.equal(ensure("claude-sonnet-4-20250514"), "claude-sonnet-4-6");
 assert.equal(alive("claude-sonnet-4-6").status, "active");
+const detail = resolveDetail("claude-opus-4-20250514");
+assert.equal(detail.resolved, "claude-opus-4-8");
+assert.ok(detail.breaking_changes.length >= 1);
+assert.equal(normalizeModel("ft:gpt-4o-mini:org:foo:bar"), "gpt-4o-mini");
+assert.equal(alive("anthropic.claude-sonnet-4-6-v1:0").provider, "bedrock");
+const gated = gate("gemini-2.0-flash", (safe) => safe);
+assert.equal(gated, "gemini-3.5-flash");
 console.log("modelalive js: ok");

package/dist/types.d.ts

@@ -46,3 +46,17 @@ export declare class ModelUnknownError extends Error {
     readonly result: AliveResult;
     constructor(result: AliveResult);
 }
+export declare class ModelDeprecatedError extends Error {
+    readonly result: AliveResult;
+    constructor(result: AliveResult);
+}
+export declare class ModelExpiringSoonError extends Error {
+    readonly result: AliveResult;
+    constructor(result: AliveResult);
+}
+export interface CheckOptions {
+    strictUnknown?: boolean | null;
+    warnDeprecated?: boolean | null;
+    warnDays?: number | null;
+    today?: Date;
+}

package/dist/types.js

@@ -14,3 +14,19 @@ export class ModelUnknownError extends Error {
         this.name = "ModelUnknownError";
     }
 }
+export class ModelDeprecatedError extends Error {
+    result;
+    constructor(result) {
+        super(result.message ?? `Model ${result.model} is deprecated`);
+        this.result = result;
+        this.name = "ModelDeprecatedError";
+    }
+}
+export class ModelExpiringSoonError extends Error {
+    result;
+    constructor(result) {
+        super(result.message ?? `Model ${result.model} retires soon`);
+        this.result = result;
+        this.name = "ModelExpiringSoonError";
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "modelalive",
-  "version": "0.5.0",
+  "version": "1.2.0",
   "description": "Pre-flight check: is this LLM model ID still alive?",
   "type": "module",
   "main": "dist/index.js",
@@ -15,7 +15,7 @@
   "scripts": {
     "build": "tsc && cp ../registry/models.json registry.json",
     "prebuild": "cp ../registry/models.json registry.json",
-    "test": "node --experimental-vm-modules node_modules/jest/bin/jest.js 2>/dev/null || npm run build && node --test dist/test/*.js"
+    "test": "npm run build && node --test dist/smoke.test.js dist/parity.test.js"
   },
   "keywords": ["llm", "anthropic", "openai", "gemini", "deprecation", "model-id"],
   "license": "MIT",