model-sunset 0.0.0-stage → 0.1.0

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,125 @@
+#!/usr/bin/env node
+import { readFileSync } from "node:fs";
+import { parseArgs } from "node:util";
+import { loadData } from "./data.js";
+import { format } from "./report.js";
+import { scanPaths, todayString } from "./scan.js";
+const HELP = `model-sunset - find hardcoded model IDs that are retired or about to be
+
+Usage:
+  model-sunset [paths...] [options]
+
+Scans files and directories (default ".") for model IDs from Anthropic, OpenAI
+and Google that have a shutdown date. Inside a git repository only tracked and
+unignored files are read.
+
+Exit code 0 when nothing reaches --fail-on, 1 when something does, 2 on bad usage.
+
+Options:
+  -f, --format <fmt>      text (default), json, github (annotations) or markdown.
+      --fail-on <level>   retired, deprecated (default) or none.
+  -w, --within <days>     Only report deprecated models that shut down within this
+                          many days. Retired models are always reported.
+  -i, --ignore <glob>     Skip matching paths. Repeatable, e.g. -i "docs/**".
+      --offline           Use the model list shipped with this version. By default
+                          the latest list is downloaded from GitHub (cached 24h).
+      --data <file|url>   Use your own models.json instead.
+      --today <date>      Compare against this date (YYYY-MM-DD) instead of today.
+      --no-color          Don't color the output.
+  -h, --help              Show this help.
+  -v, --version           Show the version number.
+
+Add "model-sunset-ignore" in a comment on a line to skip it.
+
+Examples:
+  model-sunset .
+  model-sunset src --within 90
+  model-sunset --format json > sunset.json
+`;
+const FORMATS = new Set(["text", "json", "github", "markdown"]);
+const FAIL_ON = new Set(["retired", "deprecated", "none"]);
+class UsageError extends Error {
+}
+function version() {
+    const pkg = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
+    return pkg.version;
+}
+async function main(argv) {
+    let parsed;
+    try {
+        parsed = parseArgs({
+            args: argv,
+            allowPositionals: true,
+            options: {
+                format: { type: "string", short: "f", default: "text" },
+                "fail-on": { type: "string", default: "deprecated" },
+                within: { type: "string", short: "w" },
+                ignore: { type: "string", short: "i", multiple: true, default: [] },
+                offline: { type: "boolean", default: false },
+                data: { type: "string" },
+                today: { type: "string" },
+                "no-color": { type: "boolean", default: false },
+                help: { type: "boolean", short: "h", default: false },
+                version: { type: "boolean", short: "v", default: false },
+            },
+        });
+    }
+    catch (err) {
+        throw new UsageError(err.message);
+    }
+    const { values, positionals } = parsed;
+    if (values.help) {
+        process.stdout.write(HELP);
+        return 0;
+    }
+    if (values.version) {
+        process.stdout.write(`${version()}\n`);
+        return 0;
+    }
+    const fmt = values.format;
+    if (!FORMATS.has(fmt))
+        throw new UsageError(`--format must be text, json, github or markdown, not "${fmt}"`);
+    const failOn = values["fail-on"];
+    if (!FAIL_ON.has(failOn))
+        throw new UsageError(`--fail-on must be retired, deprecated or none, not "${failOn}"`);
+    let within;
+    if (values.within !== undefined) {
+        within = Number(values.within);
+        if (!Number.isInteger(within) || within < 0)
+            throw new UsageError(`--within must be a whole number of days`);
+    }
+    const today = values.today ?? process.env.MODEL_SUNSET_TODAY ?? todayString();
+    if (!/^\d{4}-\d{2}-\d{2}$/.test(today) || Number.isNaN(Date.parse(today))) {
+        throw new UsageError(`--today must be a date like 2026-12-01`);
+    }
+    const loaded = await loadData({ offline: values.offline, source: values.data });
+    if (loaded.warning)
+        process.stderr.write(`model-sunset: ${loaded.warning}\n`);
+    const paths = positionals.length ? positionals : ["."];
+    let findings;
+    try {
+        findings = await scanPaths(paths, loaded.data.models, { today, ignore: values.ignore });
+    }
+    catch (err) {
+        const e = err;
+        if (e.code === "ENOENT")
+            throw new UsageError(`no such file or directory: ${e.path ?? paths.join(", ")}`);
+        throw err;
+    }
+    if (within !== undefined) {
+        findings = findings.filter((f) => f.status === "retired" || (f.daysLeft !== undefined && f.daysLeft <= within));
+    }
+    const color = !values["no-color"] && !process.env.NO_COLOR && process.stdout.isTTY === true;
+    process.stdout.write(`${format(findings, fmt, { color, updated: loaded.data.updated })}\n`);
+    if (failOn === "none")
+        return 0;
+    return findings.some((f) => failOn === "deprecated" || f.status === "retired") ? 1 : 0;
+}
+main(process.argv.slice(2)).then((code) => {
+    process.exitCode = code;
+}, (err) => {
+    process.stderr.write(`model-sunset: ${err.message}\n`);
+    if (err instanceof UsageError)
+        process.stderr.write("Run with --help for usage.\n");
+    process.exitCode = 2;
+});

package/dist/data.d.ts

@@ -0,0 +1,54 @@
+export interface ModelEntry {
+    /** The model ID as it appears in API calls, e.g. `"claude-3-opus-20240229"`. */
+    id: string;
+    provider: string;
+    /** Date the provider announced the deprecation (YYYY-MM-DD), when known. */
+    deprecated?: string;
+    /** Date requests start failing (YYYY-MM-DD), or `null` when not announced yet. */
+    shutdown: string | null;
+    /** Suggested replacement model ID. */
+    replacement?: string;
+    note?: string;
+    /** Other spellings of the same model, e.g. a cloud-platform ID. */
+    aliases?: string[];
+    /**
+     * Only match when the ID is quoted or assigned to a `model` key. Defaults to `true`
+     * for IDs of 10 characters or fewer (`o1`, `gpt-4`), which are too short to match anywhere.
+     */
+    strict?: boolean;
+}
+export interface ModelData {
+    version: number;
+    /** Date the list was last checked against the providers' pages (YYYY-MM-DD). */
+    updated: string;
+    sources?: Record<string, string>;
+    models: ModelEntry[];
+}
+export declare const DATA_URL = "https://raw.githubusercontent.com/acus9345/model-sunset/main/data/models.json";
+export declare function loadBundledData(): Promise<ModelData>;
+/** Parses and validates a models.json document. Throws with a readable message when it's malformed. */
+export declare function parseData(json: string, label?: string): ModelData;
+export interface LoadOptions {
+    /** Use only the data shipped with the package. */
+    offline?: boolean;
+    /** A local file path or URL to load instead of the default list. */
+    source?: string;
+    /** Directory for the cached download. */
+    cacheDir?: string;
+    fetch?: typeof globalThis.fetch;
+    /** Milliseconds to wait for the download. */
+    timeout?: number;
+}
+export interface LoadResult {
+    data: ModelData;
+    /** Where the data came from: `"bundled"`, `"cache"`, `"remote"` or the `source` you passed. */
+    from: string;
+    /** Set when the download failed and the bundled or cached list was used instead. */
+    warning?: string;
+}
+/**
+ * Loads the deprecation list. By default it downloads the latest list from GitHub (cached for
+ * 24 hours), so new shutdown dates reach you without a new release, and falls back to the
+ * bundled copy when offline. Whichever list has the newer `updated` date wins.
+ */
+export declare function loadData(options?: LoadOptions): Promise<LoadResult>;

package/dist/data.js

@@ -0,0 +1,97 @@
+import { mkdir, readFile, stat, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+export const DATA_URL = "https://raw.githubusercontent.com/acus9345/model-sunset/main/data/models.json";
+const CACHE_TTL_MS = 24 * 60 * 60 * 1000;
+const BUNDLED_URL = new URL("../data/models.json", import.meta.url);
+export async function loadBundledData() {
+    return parseData(await readFile(BUNDLED_URL, "utf8"), "bundled data");
+}
+/** Parses and validates a models.json document. Throws with a readable message when it's malformed. */
+export function parseData(json, label = "data") {
+    let raw;
+    try {
+        raw = JSON.parse(json);
+    }
+    catch (err) {
+        throw new Error(`${label} is not valid JSON: ${err.message}`);
+    }
+    const data = raw;
+    if (!data || typeof data !== "object" || !Array.isArray(data.models) || typeof data.updated !== "string") {
+        throw new Error(`${label} is missing "updated" or "models"`);
+    }
+    for (const m of data.models) {
+        if (!m || typeof m.id !== "string" || !m.id || typeof m.provider !== "string") {
+            throw new Error(`${label} has a model without "id" or "provider"`);
+        }
+        if (m.shutdown !== null && !isDate(m.shutdown)) {
+            throw new Error(`${label}: ${m.id} has an invalid shutdown date ${JSON.stringify(m.shutdown)}`);
+        }
+    }
+    return data;
+}
+function isDate(value) {
+    return typeof value === "string" && /^\d{4}-\d{2}-\d{2}$/.test(value) && !Number.isNaN(Date.parse(value));
+}
+/**
+ * Loads the deprecation list. By default it downloads the latest list from GitHub (cached for
+ * 24 hours), so new shutdown dates reach you without a new release, and falls back to the
+ * bundled copy when offline. Whichever list has the newer `updated` date wins.
+ */
+export async function loadData(options = {}) {
+    const doFetch = options.fetch ?? globalThis.fetch;
+    if (options.source) {
+        const text = /^https?:\/\//.test(options.source)
+            ? await download(options.source, doFetch, options.timeout ?? 10_000)
+            : await readFile(options.source, "utf8");
+        return { data: parseData(text, options.source), from: options.source };
+    }
+    const bundled = await loadBundledData();
+    if (options.offline)
+        return { data: bundled, from: "bundled" };
+    const cacheFile = join(options.cacheDir ?? defaultCacheDir(), "models.json");
+    const cached = await readCache(cacheFile);
+    if (cached && Date.now() - cached.mtime < CACHE_TTL_MS) {
+        return newer(cached.data, bundled) === cached.data ? { data: cached.data, from: "cache" } : { data: bundled, from: "bundled" };
+    }
+    try {
+        const text = await download(DATA_URL, doFetch, options.timeout ?? 3000);
+        const remote = parseData(text, DATA_URL);
+        await mkdir(join(cacheFile, ".."), { recursive: true })
+            .then(() => writeFile(cacheFile, text))
+            .catch(() => { });
+        return newer(remote, bundled) === remote ? { data: remote, from: "remote" } : { data: bundled, from: "bundled" };
+    }
+    catch (err) {
+        const fallback = cached && newer(cached.data, bundled) === cached.data ? cached : undefined;
+        return {
+            data: fallback?.data ?? bundled,
+            from: fallback ? "cache" : "bundled",
+            warning: `could not download the latest model list (${err.message}); using the ${fallback ? "cached" : "bundled"} copy from ${(fallback?.data ?? bundled).updated}`,
+        };
+    }
+}
+function newer(a, b) {
+    return a.updated >= b.updated ? a : b;
+}
+async function download(url, doFetch, timeout) {
+    const res = await doFetch(url, { signal: AbortSignal.timeout(timeout) });
+    if (!res.ok)
+        throw new Error(`HTTP ${res.status}`);
+    return res.text();
+}
+async function readCache(file) {
+    try {
+        const [text, info] = await Promise.all([readFile(file, "utf8"), stat(file)]);
+        return { data: parseData(text, file), mtime: info.mtimeMs };
+    }
+    catch {
+        return undefined;
+    }
+}
+function defaultCacheDir() {
+    const base = process.env.XDG_CACHE_HOME ||
+        (process.platform === "win32" ? process.env.LOCALAPPDATA : undefined) ||
+        join(homedir(), ".cache");
+    return join(base || homedir(), "model-sunset");
+}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { DATA_URL, loadBundledData, loadData, parseData } from "./data.js";
+export type { LoadOptions, LoadResult, ModelData, ModelEntry } from "./data.js";
+export { createMatcher, daysBetween, globToRegExp, listFiles, scanPaths, scanText, statusOf, todayString } from "./scan.js";
+export type { Finding, ListOptions, Matcher, ScanOptions, Status } from "./scan.js";
+export { describe, format, formatGithub, formatJson, formatMarkdown, formatText, summary } from "./report.js";
+export type { Format, ReportOptions } from "./report.js";

package/dist/index.js

@@ -0,0 +1,3 @@
+export { DATA_URL, loadBundledData, loadData, parseData } from "./data.js";
+export { createMatcher, daysBetween, globToRegExp, listFiles, scanPaths, scanText, statusOf, todayString } from "./scan.js";
+export { describe, format, formatGithub, formatJson, formatMarkdown, formatText, summary } from "./report.js";

package/dist/report.d.ts

@@ -0,0 +1,16 @@
+import type { Finding } from "./scan.js";
+export type Format = "text" | "json" | "github" | "markdown";
+export interface ReportOptions {
+    color?: boolean;
+    /** Date of the model list, shown in the summary. */
+    updated?: string;
+}
+export declare function describe(f: Finding): string;
+export declare function summary(findings: Finding[], updated?: string): string;
+export declare function formatText(findings: Finding[], options?: ReportOptions): string;
+export declare function formatJson(findings: Finding[], options?: ReportOptions): string;
+/** GitHub Actions workflow commands, which show up as annotations on the files. */
+export declare function formatGithub(findings: Finding[], options?: ReportOptions): string;
+/** A Markdown table, used for the issue the GitHub Action opens. */
+export declare function formatMarkdown(findings: Finding[], options?: ReportOptions): string;
+export declare function format(findings: Finding[], fmt: Format, options?: ReportOptions): string;

package/dist/report.js

@@ -0,0 +1,90 @@
+const paint = (on, code, s) => (on ? `\x1b[${code}m${s}\x1b[0m` : s);
+export function describe(f) {
+    if (f.status === "retired")
+        return "RETIRED";
+    if (f.daysLeft === undefined)
+        return "DEPRECATED (shutdown date not announced)";
+    return `sunset ${f.model.shutdown} (in ${f.daysLeft} day${f.daysLeft === 1 ? "" : "s"})`;
+}
+function suggestion(f) {
+    return f.model.replacement ? `suggested: ${f.model.replacement}` : "";
+}
+export function summary(findings, updated) {
+    const retired = findings.filter((f) => f.status === "retired").length;
+    const deprecated = findings.length - retired;
+    const list = updated ? ` (model list from ${updated})` : "";
+    if (!findings.length)
+        return `No retired or deprecated model IDs found${list}.`;
+    return `${findings.length} hardcoded model ID${findings.length === 1 ? "" : "s"}: ${retired} retired, ${deprecated} deprecated${list}.`;
+}
+export function formatText(findings, options = {}) {
+    const color = options.color ?? false;
+    const rows = findings.map((f) => [`${f.file}:${f.line}`, f.match, describe(f), suggestion(f)]);
+    const w0 = Math.max(0, ...rows.map((r) => r[0].length));
+    const w1 = Math.max(0, ...rows.map((r) => r[1].length));
+    const w2 = Math.max(0, ...rows.map((r) => r[2].length));
+    const lines = rows.map(([loc, id, status, next], i) => {
+        const f = findings[i];
+        const statusCell = paint(color, f.status === "retired" ? "31;1" : "33", status.padEnd(w2));
+        const arrow = next ? `  → ${next}` : "";
+        return `${paint(color, "2", loc.padEnd(w0))}   ${id.padEnd(w1)}   ${statusCell}${arrow}`.trimEnd();
+    });
+    if (lines.length)
+        lines.push("");
+    lines.push(summary(findings, options.updated));
+    return lines.join("\n");
+}
+export function formatJson(findings, options = {}) {
+    return JSON.stringify({
+        updated: options.updated,
+        findings: findings.map((f) => ({
+            file: f.file,
+            line: f.line,
+            column: f.column,
+            match: f.match,
+            id: f.model.id,
+            provider: f.model.provider,
+            status: f.status,
+            shutdown: f.model.shutdown,
+            daysLeft: f.daysLeft ?? null,
+            replacement: f.model.replacement ?? null,
+        })),
+    }, null, 2);
+}
+const ghEscape = (s) => s.replace(/%/g, "%25").replace(/\r/g, "%0D").replace(/\n/g, "%0A");
+const ghProp = (s) => ghEscape(s).replace(/:/g, "%3A").replace(/,/g, "%2C");
+/** GitHub Actions workflow commands, which show up as annotations on the files. */
+export function formatGithub(findings, options = {}) {
+    const lines = findings.map((f) => {
+        const level = f.status === "retired" ? "error" : "warning";
+        const next = f.model.replacement ? ` Suggested replacement: ${f.model.replacement}.` : "";
+        const title = `${f.match} is ${f.status === "retired" ? "retired" : "deprecated"}`;
+        return `::${level} file=${ghProp(f.file)},line=${f.line},col=${f.column},title=${ghProp(title)}::${ghEscape(`${f.match}: ${describe(f)}.${next}`)}`;
+    });
+    lines.push(summary(findings, options.updated));
+    return lines.join("\n");
+}
+/** A Markdown table, used for the issue the GitHub Action opens. */
+export function formatMarkdown(findings, options = {}) {
+    const out = [summary(findings, options.updated)];
+    if (findings.length) {
+        out.push("", "| Location | Model | Status | Suggested replacement |", "| --- | --- | --- | --- |");
+        for (const f of findings) {
+            const status = f.status === "retired" ? "**Retired**" : describe(f).replace(/^sunset/, "Shuts down");
+            out.push(`| \`${f.file}:${f.line}\` | \`${f.match}\` | ${status} | ${f.model.replacement ? `\`${f.model.replacement}\`` : ""} |`);
+        }
+    }
+    return out.join("\n");
+}
+export function format(findings, fmt, options = {}) {
+    switch (fmt) {
+        case "json":
+            return formatJson(findings, options);
+        case "github":
+            return formatGithub(findings, options);
+        case "markdown":
+            return formatMarkdown(findings, options);
+        default:
+            return formatText(findings, options);
+    }
+}

package/dist/scan.d.ts

@@ -0,0 +1,50 @@
+import type { ModelEntry } from "./data.js";
+export type Status = "retired" | "deprecated";
+export interface Finding {
+    /** Path relative to the current directory, with forward slashes. */
+    file: string;
+    line: number;
+    column: number;
+    /** The text that matched, which can be an alias of `model.id`. */
+    match: string;
+    model: ModelEntry;
+    status: Status;
+    /** Days until shutdown; negative once it has passed, `undefined` when no date is announced. */
+    daysLeft?: number;
+}
+export interface Matcher {
+    /** Finds model IDs in one line of text. */
+    matchLine(line: string): {
+        match: string;
+        column: number;
+        model: ModelEntry;
+    }[];
+}
+/** Builds a matcher for every model in the list. */
+export declare function createMatcher(models: ModelEntry[]): Matcher;
+/** Whole days from `today` to `date` (both YYYY-MM-DD). */
+export declare function daysBetween(today: string, date: string): number;
+export declare function todayString(now?: Date): string;
+export declare function statusOf(model: ModelEntry, today: string): {
+    status: Status;
+    daysLeft?: number;
+};
+/** Scans text and returns every model ID it mentions. Lines containing `model-sunset-ignore` are skipped. */
+export declare function scanText(text: string, file: string, matcher: Matcher, today: string): Finding[];
+export interface ListOptions {
+    /** Glob patterns to skip, matched against the path relative to the current directory. */
+    ignore?: string[];
+}
+/** Lists the text files to scan under each path. Inside a git repository it uses `git ls-files`, so `.gitignore` is respected. */
+export declare function listFiles(paths: string[], options?: ListOptions): Promise<string[]>;
+/** Reads a file as text, or returns `undefined` for binary or very large files. */
+export declare function readText(file: string): Promise<string | undefined>;
+export declare function displayPath(file: string): string;
+/** Converts a glob (`*`, `**`, `?`) to a regular expression. A pattern without `/` matches at any depth. */
+export declare function globToRegExp(glob: string): RegExp;
+export interface ScanOptions extends ListOptions {
+    /** Date to compare shutdown dates against (YYYY-MM-DD). Defaults to today (UTC). */
+    today?: string;
+}
+/** Scans files and directories for hardcoded model IDs that are retired or deprecated. */
+export declare function scanPaths(paths: string[], models: ModelEntry[], options?: ScanOptions): Promise<Finding[]>;

package/dist/scan.js

@@ -0,0 +1,197 @@
+import { execFile } from "node:child_process";
+import { open, readdir, stat } from "node:fs/promises";
+import { join, relative, resolve, sep } from "node:path";
+const escape = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+/** Builds a matcher for every model in the list. */
+export function createMatcher(models) {
+    const byName = new Map();
+    const loose = [];
+    const strict = [];
+    for (const model of models) {
+        const names = [model.id, ...(model.aliases ?? [])];
+        // Vertex AI spells dated Claude IDs as `claude-3-opus@20240229`.
+        const dated = /^(claude-.+)-(\d{8})$/.exec(model.id);
+        if (dated)
+            names.push(`${dated[1]}@${dated[2]}`);
+        for (const name of names) {
+            if (byName.has(name))
+                continue;
+            byName.set(name, model);
+            (model.strict ?? name.length <= 10 ? strict : loose).push(name);
+        }
+    }
+    const alternation = (names) => names
+        .sort((a, b) => b.length - a.length)
+        .map(escape)
+        .join("|");
+    // A model ID ends at anything that can't continue it. `-v1:0` is allowed after it for
+    // Bedrock IDs (`anthropic.claude-3-opus-20240229-v1:0`).
+    const end = String.raw `(?=$|-v\d|[^A-Za-z0-9_.\-]|[.\-](?![A-Za-z0-9]))`;
+    const patterns = [];
+    if (loose.length)
+        patterns.push(new RegExp(String.raw `(?<![A-Za-z0-9_\-])(?:${alternation(loose)})${end}`, "g"));
+    if (strict.length) {
+        const names = alternation(strict);
+        patterns.push(new RegExp(String.raw `(?<=["'\x60/])(?:${names})(?=["'\x60])|(?<=[Mm][Oo][Dd][Ee][Ll][A-Za-z_]*["']?\s*[:=]\s*)(?:${names})(?![A-Za-z0-9_.\-])`, "g"));
+    }
+    return {
+        matchLine(line) {
+            const hits = [];
+            for (const re of patterns) {
+                re.lastIndex = 0;
+                for (let m = re.exec(line); m; m = re.exec(line)) {
+                    const model = byName.get(m[0]);
+                    if (model && !hits.some((h) => h.column === m.index + 1))
+                        hits.push({ match: m[0], column: m.index + 1, model });
+                }
+            }
+            return hits.sort((a, b) => a.column - b.column);
+        },
+    };
+}
+/** Whole days from `today` to `date` (both YYYY-MM-DD). */
+export function daysBetween(today, date) {
+    return Math.round((Date.parse(date) - Date.parse(today)) / 86_400_000);
+}
+export function todayString(now = new Date()) {
+    return now.toISOString().slice(0, 10);
+}
+export function statusOf(model, today) {
+    if (!model.shutdown)
+        return { status: "deprecated" };
+    const daysLeft = daysBetween(today, model.shutdown);
+    return { status: daysLeft <= 0 ? "retired" : "deprecated", daysLeft };
+}
+const IGNORE_LINE = "model-sunset-ignore";
+/** Scans text and returns every model ID it mentions. Lines containing `model-sunset-ignore` are skipped. */
+export function scanText(text, file, matcher, today) {
+    const findings = [];
+    const lines = text.split(/\r?\n/);
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        if (line.length > 5000 || line.includes(IGNORE_LINE))
+            continue;
+        for (const hit of matcher.matchLine(line)) {
+            findings.push({ file, line: i + 1, column: hit.column, match: hit.match, model: hit.model, ...statusOf(hit.model, today) });
+        }
+    }
+    return findings;
+}
+const SKIP_DIRS = new Set([
+    ".git", "node_modules", "dist", "build", "out", "coverage", "vendor", ".next", ".nuxt", ".svelte-kit",
+    ".turbo", ".cache", "target", "venv", ".venv", "__pycache__", ".tox", ".mypy_cache", ".pytest_cache",
+]);
+const SKIP_FILES = new Set([
+    "package-lock.json", "npm-shrinkwrap.json", "yarn.lock", "pnpm-lock.yaml", "bun.lockb", "bun.lock",
+    "poetry.lock", "uv.lock", "Pipfile.lock", "Cargo.lock", "Gemfile.lock", "composer.lock", "go.sum",
+]);
+const BINARY_EXT = /\.(png|jpe?g|gif|webp|ico|bmp|tiff?|pdf|zip|gz|tgz|bz2|xz|7z|rar|jar|war|exe|dll|so|dylib|bin|wasm|woff2?|ttf|otf|eot|mp[34]|mov|avi|webm|wav|ogg|flac|sqlite|db|pyc|class|o|a|lib|node|map)$/i;
+const MAX_BYTES = 2 * 1024 * 1024;
+/** Lists the text files to scan under each path. Inside a git repository it uses `git ls-files`, so `.gitignore` is respected. */
+export async function listFiles(paths, options = {}) {
+    const ignore = (options.ignore ?? []).map(globToRegExp);
+    const files = new Set();
+    for (const p of paths) {
+        const info = await stat(p);
+        if (info.isFile()) {
+            files.add(resolve(p));
+            continue;
+        }
+        const fromGit = await gitFiles(p);
+        for (const f of fromGit ?? (await walk(resolve(p))))
+            files.add(f);
+    }
+    return [...files]
+        .filter((f) => {
+        const parts = f.split(sep);
+        const name = parts[parts.length - 1];
+        if (SKIP_FILES.has(name) || BINARY_EXT.test(name) || /\.min\.(js|css)$/.test(name))
+            return false;
+        if (parts.some((part) => SKIP_DIRS.has(part)))
+            return false;
+        const rel = displayPath(f);
+        return !ignore.some((re) => re.test(rel));
+    })
+        .sort();
+}
+function gitFiles(dir) {
+    return new Promise((done) => {
+        execFile("git", ["-C", dir, "ls-files", "-z", "--cached", "--others", "--exclude-standard"], { maxBuffer: 256 * 1024 * 1024 }, (err, stdout) => {
+            if (err)
+                return done(undefined);
+            done(stdout.split("\0").filter(Boolean).map((f) => resolve(dir, f)));
+        });
+    });
+}
+async function walk(dir, out = []) {
+    for (const entry of await readdir(dir, { withFileTypes: true })) {
+        if (entry.isDirectory()) {
+            if (!SKIP_DIRS.has(entry.name))
+                await walk(join(dir, entry.name), out);
+        }
+        else if (entry.isFile()) {
+            out.push(join(dir, entry.name));
+        }
+    }
+    return out;
+}
+/** Reads a file as text, or returns `undefined` for binary or very large files. */
+export async function readText(file) {
+    let handle;
+    try {
+        handle = await open(file, "r");
+        const { size } = await handle.stat();
+        if (size > MAX_BYTES)
+            return undefined;
+        const buf = await handle.readFile();
+        if (buf.subarray(0, 8000).includes(0))
+            return undefined;
+        return buf.toString("utf8");
+    }
+    catch {
+        return undefined;
+    }
+    finally {
+        await handle?.close();
+    }
+}
+export function displayPath(file) {
+    const rel = relative(process.cwd(), file);
+    return (rel && !rel.startsWith("..") ? rel : file).split(sep).join("/");
+}
+/** Converts a glob (`*`, `**`, `?`) to a regular expression. A pattern without `/` matches at any depth. */
+export function globToRegExp(glob) {
+    let g = glob.replace(/\\/g, "/").replace(/^\.\//, "");
+    if (g.endsWith("/"))
+        g += "**";
+    let re = "";
+    for (let i = 0; i < g.length; i++) {
+        const c = g[i];
+        if (c === "*") {
+            if (g[i + 1] === "*") {
+                re += g[i + 2] === "/" ? "(?:.*/)?" : ".*";
+                i += g[i + 2] === "/" ? 2 : 1;
+            }
+            else
+                re += "[^/]*";
+        }
+        else if (c === "?")
+            re += "[^/]";
+        else
+            re += escape(c);
+    }
+    const anchored = g.includes("/") ? `^${re}` : `(?:^|/)${re}`;
+    return new RegExp(`${anchored}(?:/.*)?$`);
+}
+/** Scans files and directories for hardcoded model IDs that are retired or deprecated. */
+export async function scanPaths(paths, models, options = {}) {
+    const matcher = createMatcher(models);
+    const today = options.today ?? todayString();
+    const findings = [];
+    for (const file of await listFiles(paths, options)) {
+        const text = await readText(file);
+        if (text !== undefined)
+            findings.push(...scanText(text, displayPath(file), matcher, today));
+    }
+    return findings;
+}