arol-ai 0.1.2 → 0.1.4

package/README.md

@@ -72,13 +72,18 @@ Detection keys on **actual usage, not mere SDK presence.** Each dataset entry de
 Flags **only** when your code actually references the deprecated API in a scanned **source file**. `detect.sdk` is just a scope hint here and is **never** a trigger on its own. A `pattern` entry carries two kinds of usage signal:
 
 - **`detect.patterns`** — raw regexes for code identifiers, endpoints, and params (e.g. `beta\.assistants`, `/v1/threads`, `charges\.create`, `hapikey\s*=`). Matched anywhere in the file.
-- **`detect.models`** — model family names matched **only inside a string literal**. Each becomes: an opening quote (`'` `"` or `` ` ``), the family name, an optional `[A-Za-z0-9._-]*` version/suffix, then the matching closing quote. So `"gpt-4o"`, `'gpt-4o'`, `` `gpt-4o` ``, and `"gpt-4o-2024-05-13"` match — but the same name sitting in prose, JSX, or a comment does **not**.
+- **`detect.models`** — model family names matched **only inside a string literal**. Each becomes: an opening quote (`'` `"` or `` ` ``), the family name, an **optional ISO date snapshot** (`-YYYY-MM-DD`), then the matching closing quote — no arbitrary trailing characters. So `"gpt-4o"`, `'gpt-4o'`, `` `gpt-4o` ``, and `"gpt-4o-2024-05-13"` match, but a *different* model like `"gpt-4o-mini"` or `"gpt-4o-realtime-preview"` does **not** (and neither does a bare mention in prose, JSX, or a comment).
 
 This split is what keeps a marketing page that mentions *"GPT-4o, GPT-4.1, and o4-mini"* from being reported as deprecated usage: those names aren't quoted string literals, so `detect.models` ignores them. Only something like `model: "o4-mini"` counts.
 
+Two more layers keep matches context-aware:
+
+- **Language scoping (`applies_to`).** Each entry lists the file extensions its signals are valid in (e.g. `["py"]`, `["js","ts","jsx","tsx","mjs"]`, or `["*"]` for model strings). An entry is only tested against files with a matching extension, so a Python-only pattern like `openai.ChatCompletion` never fires in a `.tsx` file. Defaults to `["*"]` when omitted.
+- **Comment stripping.** Before matching, comments are blanked out per language — `//`, `/* */`, JSX `{/* */}`, and `#` (Python). Stripping is string-aware: a marker inside a string literal (e.g. the `//` in `"https://…"`) is **not** treated as a comment, and offsets are preserved so reported line numbers stay exact. A commented-out `model: "gpt-4o"` is ignored; the real call on the next line is not.
+
 Each hit records the **file path, line number, and matched text**, and one deprecation aggregates **all** of its matched locations into a single finding.
 
-> Having the `openai` package in `requirements.txt` does **not** flag the Assistants API deprecation. Your code has to actually use `beta.assistants` / a deprecated model id (etc.).
+> Having the `openai` package in `requirements.txt` does **not** flag the Assistants API deprecation. Your code has to actually use `beta.assistants` / a deprecated model id (etc.), in a file of the right language, outside comments.
 
 **Files scanned / skipped**
 
@@ -112,16 +117,19 @@ arol-ai scan [path] [options]
 | `--no-color` | Disable colored output (also respects `NO_COLOR`) |
 | `--data <file>` | Use a custom `deprecations.json` instead of the bundled one |
 | `--ignore <glob>` | Skip files matching this glob; repeatable. Combined with `.arolignore`. e.g. `--ignore 'docs/**' --ignore '**/*.gen.ts'` |
-| `--fail-on <severity>` | Exit non-zero if findings meet a level: `high` \| `medium` \| `low` \| `any` \| `none` (default `none`) |
+| `--within <days>` | Window (default `30`) for the CI gate's "scheduled soon" check. See exit codes. |
 | `-v, --version` | Print the version |
 | `-h, --help` | Show help |
 
 `scan` is the default command, so `arol-ai ./repo` works too.
 
-**Exit codes:** `0` success · `1` `--fail-on` threshold met · `2` bad path or dataset error. The `--fail-on` flag makes `arol-ai` useful as a CI gate:
+**Exit codes:** `0` success · `1` an actionable finding · `2` bad path or dataset error.
+
+A finding is **actionable** (exit `1`) when it is **high**-severity, or **scheduled** to sunset within `--within` days (default 30). Dateless `deprecated` findings and non-imminent `medium`/`low` findings are **warn-only** (still printed, but exit `0`). This makes `arol-ai` a sensible CI gate with no flags:
 
 ```sh
-npx arol-ai scan --fail-on high
+npx arol-ai scan            # fails CI on high or imminently-scheduled findings
+npx arol-ai scan --within 7 # only fail when a sunset is within a week
 ```
 
 Colors are automatically disabled when output is not a TTY (e.g. piped to a file), or when `NO_COLOR` is set. Use `FORCE_COLOR=1` to force them on.
@@ -142,7 +150,8 @@ The dataset is either a bare array of entries, or a `{ "deprecations": [ ... ] }
   "title": "Assistants API (beta)", // short headline (required)
   "severity": "high",               // "high" | "medium" | "low" (required)
   "match": "pattern",               // "pattern" (default) | "sdk" | "version"
-  "sunset_date": "2026-08-26",      // ISO YYYY-MM-DD, or "" if no fixed date
+  "applies_to": ["py","js","ts","jsx","tsx","mjs"], // extensions to test; ["*"] = any
+  "sunset_date": "2026-08-26",      // ISO YYYY-MM-DD, or null if no date announced
   "detect": {
     "sdk": ["openai"],              // scope hint for "pattern"; the trigger for "sdk"/"version"
     "patterns": [                   // raw regexes: identifiers, endpoints, params
@@ -157,7 +166,7 @@ The dataset is either a bare array of entries, or a `{ "deprecations": [ ... ] }
 }
 ```
 
-A model-retirement entry uses `detect.models` so it only fires on a quoted model id, never on prose:
+A model-retirement entry uses `detect.models` (and `applies_to: ["*"]`) so it only fires on a quoted model id, in any language, never on prose:
 
 ```jsonc
 {
@@ -166,6 +175,7 @@ A model-retirement entry uses `detect.models` so it only fires on a quoted model
   "title": "GPT-4 family models (API shutdown)",
   "severity": "high",
   "match": "pattern",
+  "applies_to": ["*"],
   "sunset_date": "2026-10-23",
   "detect": {
     "sdk": ["openai"],
@@ -177,6 +187,23 @@ A model-retirement entry uses `detect.models` so it only fires on a quoted model
 }
 ```
 
+A Python-only entry scopes itself with `applies_to: ["py"]`, so its patterns never fire in JS/TSX files that merely mention the API in prose:
+
+```jsonc
+{
+  "id": "openai-python-v0-syntax",
+  "vendor": "OpenAI",
+  "title": "Legacy openai-python v0 call syntax",
+  "severity": "high",
+  "match": "pattern",
+  "applies_to": ["py"],
+  "sunset_date": "2023-11-06",
+  "detect": { "sdk": ["openai"], "patterns": ["openai\\.ChatCompletion"] },
+  "migration_url": "https://github.com/openai/openai-python/discussions/742",
+  "summary": "Instantiate a client: client.chat.completions.create(...)."
+}
+```
+
 A `version` entry instead flags on the installed SDK version (no patterns needed):
 
 ```jsonc
@@ -187,13 +214,31 @@ A `version` entry instead flags on the installed SDK version (no patterns needed
   "severity": "medium",
   "match": "version",
   "version_range": "<3.0.0",        // flags only when the declared version is in range
-  "sunset_date": "",
+  "sunset_date": null,
   "detect": { "sdk": ["example-sdk"], "patterns": [] },
   "migration_url": "https://example.com/migrate",
   "summary": "Upgrade example-sdk to v3+."
 }
 ```
 
+A **dateless** entry — deprecated with no removal date announced. `sunset_date: null`
+makes its status `deprecated`; it renders *"deprecated · no removal date announced"* and
+is warn-only (exit 0) unless it's high-severity:
+
+```jsonc
+{
+  "id": "resend-audiences-deprecated",
+  "vendor": "Resend",
+  "title": "Audiences API (deprecated in favor of Segments)",
+  "severity": "medium",
+  "match": "pattern",
+  "sunset_date": null,              // no removal date → status derives to "deprecated"
+  "detect": { "sdk": ["resend"], "patterns": ["\\.audiences\\."] },
+  "migration_url": "https://resend.com/docs/dashboard/segments",
+  "summary": "Migrate audiences.* calls to the Segments API."
+}
+```
+
 ### Field reference
 
 | Field | Type | Required | Notes |
@@ -201,13 +246,15 @@ A `version` entry instead flags on the installed SDK version (no patterns needed
 | `id` | string | ✓ | Unique, stable slug. |
 | `vendor` | string | ✓ | Displayed before the title. |
 | `title` | string | ✓ | Short headline for the finding. |
-| `severity` | `"high"` \| `"medium"` \| `"low"` | ✓ | Drives color, sort order, and `--fail-on`. |
+| `severity` | `"high"` \| `"medium"` \| `"low"` | ✓ | Drives color, sort order, and the CI gate (high always fails). |
 | `match` | `"pattern"` \| `"sdk"` \| `"version"` | – | How the entry is triggered. **Defaults to `"pattern"`** when omitted. See [How detection works](#how-detection-works). |
+| `status` | `"deprecated"` \| `"scheduled"` \| `"retired"` | – | Lifecycle status. **Usually omit** — it's derived at runtime from `sunset_date`. Set explicitly only to override (e.g. force `"deprecated"`). |
+| `applies_to` | string[] | – | File extensions (no dot) the entry's patterns/models are tested against, e.g. `["py"]` or `["js","ts","jsx","tsx","mjs"]`. Use `["*"]` for any file (model strings). **Defaults to `["*"]`** when omitted. |
 | `version_range` | string | – | For `match: "version"` only — e.g. `"<3.0.0"`, `">=1.2.0"`, `"=2.1.0"`. If omitted, a `version` entry behaves like `"sdk"`. |
-| `sunset_date` | string | – | ISO `YYYY-MM-DD`. Use `""` for unmaintained/no-fixed-date items; the report shows a relative hint (e.g. *"in 42 days"* / *"passed 12 days ago"*). |
+| `sunset_date` | string \| null | – | ISO `YYYY-MM-DD`, or **`null`** when no removal date is announced. Derived status: `null` → `deprecated`, future → `scheduled` (`"sunsets {date} (in N days)"`), past → `retired` (`"retired {date} (N days ago)"`). A dateless entry renders *"deprecated · no removal date announced"* and never runs date math. |
 | `detect.sdk` | string[] | – | Manifest dependency/module names. For `match: "pattern"` this is only a **scope hint and never triggers** a finding; for `sdk`/`version` it is the trigger. |
 | `detect.patterns` | string[] | – | **JSON-escaped** regex strings (so `\d` becomes `\\d`). For code identifiers, endpoints, and params. Matched anywhere in a source file; invalid regexes are skipped safely. |
-| `detect.models` | string[] | – | Model family names matched **only inside string literals** (quote-anchored, with an optional version suffix). Use this for model ids so prose/JSX mentions don't false-positive. Write the raw name (e.g. `gpt-4.5-preview`) — escaping is automatic. |
+| `detect.models` | string[] | – | Model family names matched **only inside string literals** (quote-anchored; allows an optional trailing ISO date snapshot `-YYYY-MM-DD`, nothing else). Use this for model ids so prose/JSX mentions don't false-positive and a family never matches a different model. Write the raw name (e.g. `gpt-4.5-preview`) — escaping is automatic. List dated/revisioned snapshots explicitly if they use a non-ISO suffix (e.g. Anthropic's `-20241022`). |
 | `migration_url` | string | – | Link shown in the report. |
 | `summary` | string | – | One or two sentences of guidance. |
 
@@ -216,7 +263,7 @@ A `version` entry instead flags on the installed SDK version (no patterns needed
 ### Writing good patterns & models
 
 - **Put model ids in `detect.models`, not `detect.patterns`.** A bare model id as a raw pattern matches prose, JSX, comments, and changelogs. `detect.models` requires a quoted string literal, which is what real usage looks like (`model: "o4-mini"`).
-- For `detect.models`, write the **raw family name** (e.g. `gpt-4.5-preview`, `claude-opus-4-20250514`) — escaping and quote-anchoring are automatic. The optional suffix means `gpt-4o` also catches `"gpt-4o-2024-05-13"`, so pick a family specific enough not to swallow a non-deprecated successor.
+- For `detect.models`, write the **raw family name** (e.g. `gpt-4.5-preview`, `claude-opus-4-20250514`) — escaping and quote-anchoring are automatic. Matching is exact except for an optional trailing ISO date snapshot, so `gpt-4o` catches `"gpt-4o"` and `"gpt-4o-2024-05-13"` but **not** `"gpt-4o-mini"`. If a deprecated snapshot uses a non-ISO suffix (Anthropic's `claude-3-5-sonnet-20241022`, Gemini's `gemini-1.5-pro-002`), add that full id as its own `models` entry.
 - For `detect.patterns`, match the **deprecated surface itself** — the method/property (`beta\.assistants`), endpoint path (`/v1/threads`), or param (`hapikey\s*=`) — not the import or package name. Importing an SDK isn't usage; calling the removed API is. Keep them specific (`client\.chat` is too broad — it hits unrelated SDKs).
 - Patterns are matched **case-sensitively** with the global flag over each file's contents; the file path, line number, and matched text are reported.
 - Escape backslashes (and literal dots) for JSON: a regex `beta\.assistants` is written `"beta\\.assistants"`. (Model entries don't need this — write `gpt-4.5-preview` as-is.)

package/dist/cli.js

@@ -40,6 +40,7 @@ const commander_1 = require("commander");
 const data_1 = require("./data");
 const scanner_1 = require("./scanner");
 const report_1 = require("./report");
+const status_1 = require("./status");
 /** Read this package's version without importing across the rootDir boundary. */
 function readVersion() {
     try {
@@ -61,7 +62,8 @@ function shouldUseColor(colorFlag) {
         return true;
     return Boolean(process.stdout.isTTY);
 }
-const SEVERITY_RANK = { high: 3, medium: 2, low: 1 };
+/** Default window (days) within which a scheduled finding fails the CI gate. */
+const DEFAULT_WITHIN_DAYS = 30;
 /** Commander collector so --ignore can be passed multiple times. */
 function collectIgnore(value, previous) {
     return previous.concat([value]);
@@ -96,6 +98,8 @@ function runScan(targetPath, opts) {
         ignore: opts.ignore,
         dataPath: opts.data,
     });
+    // One clock for the whole run, so rendering and the exit gate agree.
+    const now = new Date();
     if (opts.json) {
         const counts = { high: 0, medium: 0, low: 0 };
         for (const f of result.findings)
@@ -111,6 +115,7 @@ function runScan(targetPath, opts) {
                 title: f.deprecation.title,
                 severity: f.deprecation.severity,
                 match: f.deprecation.match,
+                status: (0, status_1.effectiveStatus)(f.deprecation, now),
                 sunset_date: f.deprecation.sunset_date,
                 migration_url: f.deprecation.migration_url,
                 summary: f.deprecation.summary,
@@ -121,19 +126,29 @@ function runScan(targetPath, opts) {
         process.stdout.write(JSON.stringify(payload, null, 2) + "\n");
     }
     else {
-        const report = (0, report_1.renderReport)(result, { color: shouldUseColor(opts.color) });
+        const report = (0, report_1.renderReport)(result, {
+            color: shouldUseColor(opts.color),
+            now,
+        });
         process.stdout.write(report + "\n");
     }
-    // Optional CI gate: exit non-zero if a finding meets/exceeds the threshold.
-    const failOn = opts.failOn?.toLowerCase();
-    if (failOn && failOn !== "none") {
-        const threshold = failOn === "any"
-            ? 1
-            : SEVERITY_RANK[failOn] ?? Number.POSITIVE_INFINITY;
-        const tripped = result.findings.some((f) => SEVERITY_RANK[f.deprecation.severity] >= threshold);
-        if (tripped)
-            process.exitCode = 1;
-    }
+    // CI gate: exit non-zero only for an actionable finding — any "high"-severity
+    // finding, or a "scheduled" finding landing within `--within` days (default 30).
+    // Dateless "deprecated" and non-imminent medium/low findings are warn-only.
+    const parsedWithin = opts.within !== undefined ? parseInt(opts.within, 10) : NaN;
+    const within = Number.isFinite(parsedWithin) && parsedWithin >= 0
+        ? parsedWithin
+        : DEFAULT_WITHIN_DAYS;
+    const tripped = result.findings.some((f) => {
+        if (f.deprecation.severity === "high")
+            return true;
+        if ((0, status_1.effectiveStatus)(f.deprecation, now) !== "scheduled")
+            return false;
+        const days = (0, status_1.daysUntil)(f.deprecation.sunset_date, now);
+        return days !== null && days >= 0 && days <= within;
+    });
+    if (tripped)
+        process.exitCode = 1;
 }
 function main(argv) {
     const program = new commander_1.Command();
@@ -150,7 +165,7 @@ function main(argv) {
         .option("--no-color", "disable colored output")
         .option("--data <file>", "use a custom deprecations.json dataset instead of the bundled one")
         .option("--ignore <glob>", "skip files matching this glob (repeatable); also reads .arolignore", collectIgnore, [])
-        .option("--fail-on <severity>", "exit non-zero if findings meet this level: high | medium | low | any | none", "none")
+        .option("--within <days>", "fail (exit 1) on scheduled sunsets landing within this many days (default 30); high-severity findings always fail")
         .action((pathArg, options) => {
         runScan(pathArg, options);
     });

package/dist/data.js

@@ -38,6 +38,7 @@ const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 const SEVERITIES = ["high", "medium", "low"];
 const MATCH_MODES = ["pattern", "sdk", "version"];
+const STATUSES = ["deprecated", "scheduled", "retired"];
 /**
  * Locate the bundled deprecations.json. Tries several candidate locations so the
  * tool works both when running the compiled output (dist/) from a published
@@ -89,6 +90,17 @@ function coerceDeprecation(raw) {
     const version_range = isNonEmptyString(r.version_range)
         ? r.version_range
         : undefined;
+    // Dateless deprecations: null / missing / "" all mean "no removal date".
+    const sunset_date = isNonEmptyString(r.sunset_date) ? r.sunset_date : null;
+    // Honor an explicit, valid status; otherwise leave it for runtime derivation.
+    const status = STATUSES.includes(r.status)
+        ? r.status
+        : undefined;
+    // Language scoping: extensions this entry's patterns are valid in.
+    // Normalize to lowercase, dot-stripped; default to ["*"] (match any file).
+    const applies_to = isStringArray(r.applies_to) && r.applies_to.length > 0
+        ? r.applies_to.map((e) => e.toLowerCase().replace(/^\./, ""))
+        : ["*"];
     // Drop entries that can never fire under their match mode.
     // A "pattern" entry fires on either a raw pattern OR a model-string match.
     if (match === "pattern" && patterns.length === 0 && models.length === 0)
@@ -101,7 +113,9 @@ function coerceDeprecation(raw) {
         title: r.title,
         severity: r.severity,
         match,
-        sunset_date: typeof r.sunset_date === "string" ? r.sunset_date : "",
+        status,
+        applies_to,
+        sunset_date,
         detect: { sdk, patterns, models },
         version_range,
         migration_url: typeof r.migration_url === "string" ? r.migration_url : "",

package/dist/report.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.renderReport = renderReport;
+const status_1 = require("./status");
 function makeStyler(enabled) {
     const wrap = (open, close) => (s) => enabled ? `\x1b[${open}m${s}\x1b[${close}m` : s;
     return {
@@ -40,32 +41,28 @@ function severityPill(s, sev) {
         return s.bgYellow(s.black(s.bold(label)));
     return s.bgBlue(s.white(s.bold(label)));
 }
-/** Render the sunset date with a relative hint, or a note when there is no date. */
-function sunsetPhrase(s, sunsetDate, now) {
-    if (!sunsetDate) {
-        return s.gray("no fixed sunset date — already deprecated / unmaintained");
+function dayCount(n) {
+    return `${n} ${n === 1 ? "day" : "days"}`;
+}
+/**
+ * Render the lifecycle line for a finding, keyed on its (effective) status.
+ * Date math runs ONLY for dated statuses, so a null sunset_date never produces NaN.
+ */
+function statusPhrase(s, d, now) {
+    const status = (0, status_1.effectiveStatus)(d, now);
+    const days = (0, status_1.daysUntil)(d.sunset_date, now);
+    // Dateless (or, defensively, a dated status with no parseable date).
+    if (status === "deprecated" || days === null) {
+        return s.yellow("deprecated · no removal date announced — migrate before it's pulled");
     }
-    const parsed = new Date(`${sunsetDate}T00:00:00Z`);
-    if (Number.isNaN(parsed.getTime())) {
-        return s.gray(`sunsets ${sunsetDate}`);
+    if (status === "retired") {
+        const ago = Math.abs(days);
+        return s.red(`retired ${d.sunset_date} (${dayCount(ago)} ago)`);
     }
-    const msPerDay = 24 * 60 * 60 * 1000;
-    const days = Math.round((parsed.getTime() - now.getTime()) / msPerDay);
-    let rel;
-    if (days > 1)
-        rel = `in ${days} days`;
-    else if (days === 1)
-        rel = "in 1 day";
-    else if (days === 0)
-        rel = "today";
-    else if (days === -1)
-        rel = "1 day ago";
-    else
-        rel = `${Math.abs(days)} days ago`;
-    const base = `sunsets ${sunsetDate}`;
-    const hint = days <= 0 ? ` (passed ${rel})` : ` (${rel})`;
-    // Past or imminent sunsets are the urgent ones.
-    return days <= 30 ? s.red(base + hint) : s.yellow(base + hint);
+    // scheduled
+    const rel = days <= 0 ? "today" : `in ${dayCount(days)}`;
+    const line = `sunsets ${d.sunset_date} (${rel})`;
+    return days <= 30 ? s.red(line) : s.yellow(line);
 }
 /** One line per source location: "path:line  →  matched text". */
 function formatPatternMatches(s, finding) {
@@ -98,9 +95,10 @@ function renderReport(result, opts) {
             SEVERITY_ORDER[b.deprecation.severity];
         if (sevDiff !== 0)
             return sevDiff;
-        // Within a severity, soonest/earliest sunset first; undated last.
-        const da = a.deprecation.sunset_date || "9999-99-99";
-        const db = b.deprecation.sunset_date || "9999-99-99";
+        // Within a severity, soonest sunset first; dateless ("deprecated") entries
+        // sort last. A null/empty date maps to a far-future sentinel (no throwing).
+        const da = a.deprecation.sunset_date || "9999-12-31";
+        const db = b.deprecation.sunset_date || "9999-12-31";
         return da.localeCompare(db);
     });
     // Header.
@@ -114,7 +112,7 @@ function renderReport(result, opts) {
     if (findings.length === 0) {
         out.push(s.green(s.bold("✓ No upcoming deprecations detected in your stack.")));
         out.push("");
-        out.push(footer(s, findings));
+        out.push(footer(s, findings, now));
         return out.join("\n");
     }
     // Severity summary.
@@ -136,7 +134,7 @@ function renderReport(result, opts) {
         const d = finding.deprecation;
         const sevColor = severityColor(s, d.severity);
         out.push(`${sevColor("●")} ${s.bold(d.vendor)} ${s.gray("·")} ${d.title} ${severityPill(s, d.severity)}`);
-        out.push(`  ${sunsetPhrase(s, d.sunset_date, now)}`);
+        out.push(`  ${statusPhrase(s, d, now)}`);
         if (d.summary) {
             out.push(`  ${s.dim(wrapText(d.summary, 76, "  ").trimStart())}`);
         }
@@ -156,28 +154,26 @@ function renderReport(result, opts) {
         }
         out.push("");
     }
-    out.push(footer(s, findings));
+    out.push(footer(s, findings, now));
     return out.join("\n");
 }
-/** Severity-aware closing CTA, visually separated from the findings above. */
-function footer(s, findings) {
+/** Status-aware closing CTA, visually separated from the findings above. */
+function footer(s, findings, now) {
     const sep = s.dim("─".repeat(60));
     const brand = "arol.ai";
-    let message;
-    if (findings.some((f) => f.deprecation.severity === "high")) {
-        // Prominent: high-severity items break on fixed dates.
-        message = s.bold(s.red(`⚠ These break on fixed dates. Get alerted before the next one hits you → ${brand}`));
-    }
-    else if (findings.length > 0) {
-        message =
-            s.dim("Get continuous deprecation alerts for your stack → ") +
-                s.cyan(s.bold(brand));
-    }
-    else {
-        message =
-            s.green("✓ Clean today — but new deprecations land constantly. Stay covered → ") +
-                s.cyan(s.bold(brand));
+    if (findings.length === 0) {
+        const message = s.green("✓ Clean today — but new deprecations land constantly. Stay covered → ") +
+            s.cyan(s.bold(brand));
+        return [sep, message].join("\n");
     }
+    // The urgent line only makes sense when something actually breaks on a date:
+    // a high-severity finding, or any dated (scheduled/retired) finding.
+    const hasHighOrDated = findings.some((f) => f.deprecation.severity === "high" ||
+        (0, status_1.effectiveStatus)(f.deprecation, now) !== "deprecated");
+    const message = hasHighOrDated
+        ? s.bold(s.red(`⚠ These break on fixed dates. Get alerted before the next one hits you → ${brand}`))
+        : s.yellow("Deprecated APIs in your stack will be pulled eventually — stay ahead → ") +
+            s.cyan(s.bold(brand));
     return [sep, message].join("\n");
 }
 /** Soft-wrap text to a width, indenting continuation lines. */

package/dist/scanner.js

@@ -91,13 +91,14 @@ function escapeRegex(s) {
 }
 /**
  * Build a regex that matches a model family ONLY inside a string literal:
- * an opening quote, the (escaped) family name, an optional version/suffix, then
- * the SAME closing quote. So a quoted model id (single, double, or backtick)
- * and its versioned snapshots match, but never a bare occurrence in
- * prose/JSX/markdown.
+ * an opening quote, the (escaped) family name, an OPTIONAL ISO date snapshot
+ * suffix (e.g. -2024-05-13), then the SAME closing quote. No arbitrary trailing
+ * characters are allowed, so "gpt-4o" matches "gpt-4o" and "gpt-4o-2024-05-13"
+ * but never a different model like "gpt-4o-mini" or "gpt-4o-realtime-preview".
+ * The model is still only found inside a quoted literal, never in bare prose.
  */
 function modelRegexSource(family) {
-    return `(${QUOTE_CLASS})${escapeRegex(family)}[A-Za-z0-9._-]*\\1`;
+    return `(${QUOTE_CLASS})${escapeRegex(family)}(?:-\\d{4}-\\d{2}-\\d{2})?\\1`;
 }
 function compileDeprecations(deprecations) {
     return deprecations.map((deprecation) => {
@@ -121,9 +122,110 @@ function compileDeprecations(deprecations) {
                 // Defensive: a pathological family name must not crash the scan.
             }
         }
-        return { deprecation, regexes };
+        const appliesTo = new Set((deprecation.applies_to.length > 0 ? deprecation.applies_to : ["*"]).map((e) => e.toLowerCase()));
+        return { deprecation, regexes, appliesTo };
     });
 }
+/** True if a compiled entry should be tested against a file with this extension. */
+function appliesToExt(compiled, ext) {
+    return compiled.appliesTo.has("*") || compiled.appliesTo.has(ext);
+}
+function commentConfig(ext) {
+    switch (ext) {
+        case "js":
+        case "mjs":
+        case "cjs":
+        case "jsx":
+        case "ts":
+        case "mts":
+        case "cts":
+        case "tsx":
+        case "go":
+            return { line: ["//"], block: [["/*", "*/"]], strings: ["'", '"', "`"], triple: [] };
+        case "py":
+            return { line: ["#"], block: [], strings: ["'", '"'], triple: ['"""', "'''"] };
+        default:
+            return null;
+    }
+}
+/**
+ * Replace comments with spaces so they don't match, while preserving the exact
+ * byte length and all newlines — line/column offsets stay correct. String literals
+ * (including their contents) are left intact, so a comment marker inside a string
+ * (e.g. "https://…") is NOT treated as a comment.
+ */
+function stripComments(src, cfg) {
+    const out = src.split("");
+    const n = src.length;
+    const at = (s, i) => src.startsWith(s, i);
+    const blank = (from, to) => {
+        for (let k = from; k < to; k++)
+            if (out[k] !== "\n")
+                out[k] = " ";
+    };
+    let i = 0;
+    while (i < n) {
+        // Triple-quoted strings (Python) — checked before single quotes.
+        let matched = false;
+        for (const t of cfg.triple) {
+            if (at(t, i)) {
+                i += t.length;
+                while (i < n && !at(t, i))
+                    i++;
+                i += t.length;
+                matched = true;
+                break;
+            }
+        }
+        if (matched)
+            continue;
+        // Ordinary string literals — preserve contents verbatim.
+        for (const q of cfg.strings) {
+            if (src[i] === q) {
+                i++;
+                while (i < n && src[i] !== q) {
+                    if (src[i] === "\\")
+                        i++; // skip escaped char
+                    i++;
+                }
+                i++; // closing quote (or past end if unterminated)
+                matched = true;
+                break;
+            }
+        }
+        if (matched)
+            continue;
+        // Block comments.
+        for (const [open, close] of cfg.block) {
+            if (at(open, i)) {
+                const end = src.indexOf(close, i + open.length);
+                const stop = end === -1 ? n : end + close.length;
+                blank(i, stop);
+                i = stop;
+                matched = true;
+                break;
+            }
+        }
+        if (matched)
+            continue;
+        // Line comments.
+        for (const lc of cfg.line) {
+            if (at(lc, i)) {
+                let k = i;
+                while (k < n && src[k] !== "\n")
+                    k++;
+                blank(i, k);
+                i = k;
+                matched = true;
+                break;
+            }
+        }
+        if (matched)
+            continue;
+        i++;
+    }
+    return out.join("");
+}
 /** Precompute the byte offset at which each line starts. */
 function computeLineStarts(content) {
     const starts = [0];
@@ -354,7 +456,16 @@ function scanRepo(root, deprecations, options = {}) {
             continue;
         }
         scannedFiles++;
-        scanContent(content, rel, compiled, patternSink);
+        // Language scoping: only test entries valid for this file's extension.
+        const ext = path.extname(rel).slice(1).toLowerCase();
+        const applicable = compiled.filter((c) => appliesToExt(c, ext));
+        if (applicable.length === 0)
+            continue;
+        // Comment stripping: match against de-commented source so mentions in
+        // comments don't count. Offsets are preserved, so line numbers stay correct.
+        const cfg = commentConfig(ext);
+        const scanText = cfg ? stripComments(content, cfg) : content;
+        scanContent(scanText, rel, applicable, patternSink);
     }
     // 3. Build findings — one per deprecation, evaluated per its match mode.
     const findings = [];

package/dist/status.js

@@ -0,0 +1,45 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseSunsetDate = parseSunsetDate;
+exports.daysUntil = daysUntil;
+exports.effectiveStatus = effectiveStatus;
+const MS_PER_DAY = 24 * 60 * 60 * 1000;
+/** Midnight-UTC timestamp for a Date's calendar day. */
+function startOfDayUTC(d) {
+    return Date.UTC(d.getUTCFullYear(), d.getUTCMonth(), d.getUTCDate());
+}
+/**
+ * Parse an ISO `YYYY-MM-DD` sunset date to a UTC midnight timestamp.
+ * Returns null for null/empty/unparseable input — callers must treat null as
+ * "no usable date" and skip all date math.
+ */
+function parseSunsetDate(date) {
+    if (!date)
+        return null;
+    const t = new Date(`${date}T00:00:00Z`).getTime();
+    return Number.isNaN(t) ? null : t;
+}
+/**
+ * Whole calendar days from today to the sunset date: positive = in the future,
+ * negative = in the past, 0 = today. Returns null when there is no usable date,
+ * so the result can never be NaN.
+ */
+function daysUntil(date, now) {
+    const t = parseSunsetDate(date);
+    if (t === null)
+        return null;
+    return Math.round((t - startOfDayUTC(now)) / MS_PER_DAY);
+}
+/**
+ * The effective status for a finding. An explicit `status` is always honored;
+ * otherwise it is derived from sunset_date relative to `now`:
+ *   null/absent → "deprecated", past → "retired", today or future → "scheduled".
+ */
+function effectiveStatus(d, now) {
+    if (d.status)
+        return d.status;
+    const t = parseSunsetDate(d.sunset_date);
+    if (t === null)
+        return "deprecated";
+    return t < startOfDayUTC(now) ? "retired" : "scheduled";
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arol-ai",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Scan a local repo for upcoming third-party API/SDK deprecations. Fully local — no network, no telemetry, your code never leaves the machine.",
   "keywords": [
     "deprecation",

package/src/data/deprecations.json

@@ -5,6 +5,7 @@
     "title": "Assistants API (beta)",
     "severity": "high",
     "match": "pattern",
+    "applies_to": ["py", "js", "ts", "jsx", "tsx", "mjs"],
     "sunset_date": "2026-08-26",
     "detect": {
       "sdk": ["openai"],
@@ -25,6 +26,7 @@
     "title": "Claude Sonnet 4 & Opus 4",
     "severity": "high",
     "match": "pattern",
+    "applies_to": ["*"],
     "sunset_date": "2026-06-15",
     "detect": {
       "sdk": ["@anthropic-ai/sdk", "anthropic"],
@@ -46,6 +48,7 @@
     "title": "Retired Claude models (Haiku 3, 3.5/3.7 Sonnet, Claude 2.x)",
     "severity": "high",
     "match": "pattern",
+    "applies_to": ["*"],
     "sunset_date": "2026-04-20",
     "detect": {
       "sdk": ["@anthropic-ai/sdk", "anthropic"],
@@ -69,6 +72,7 @@
     "title": "Gemini 2.5 Pro / Flash / Flash-Lite",
     "severity": "high",
     "match": "pattern",
+    "applies_to": ["*"],
     "sunset_date": "2026-10-16",
     "detect": {
       "sdk": ["@google/generative-ai", "@google/genai", "google-generativeai"],
@@ -85,6 +89,7 @@
     "title": "Gemini 2.0 Flash family",
     "severity": "high",
     "match": "pattern",
+    "applies_to": ["*"],
     "sunset_date": "2026-06-01",
     "detect": {
       "sdk": ["@google/generative-ai", "@google/genai", "google-generativeai"],
@@ -106,42 +111,37 @@
     "title": "Gemini 1.0 / 1.5 models",
     "severity": "high",
     "match": "pattern",
+    "applies_to": ["*"],
     "sunset_date": "2026-04-29",
     "detect": {
       "sdk": ["@google/generative-ai", "@google/genai", "google-generativeai"],
       "patterns": [],
-      "models": ["gemini-1.5-pro", "gemini-1.5-flash", "gemini-1.0-pro", "gemini-pro"]
+      "models": [
+        "gemini-1.5-pro",
+        "gemini-1.5-flash",
+        "gemini-1.0-pro",
+        "gemini-pro"
+      ]
     },
     "migration_url": "https://ai.google.dev/gemini-api/docs/deprecations",
     "summary": "All Gemini 1.0 and 1.5 models are shut down and return 404. Migrate to Gemini 2.5+ or 3.x.",
     "source": "https://firebase.google.com/docs/ai-logic/models"
   },
   {
-    "id": "openai-gpt4-family-shutdown",
+    "id": "openai-retired-gpt4-variants",
     "vendor": "OpenAI",
-    "title": "GPT-4 family models (API shutdown)",
+    "title": "Retired GPT-4 preview/variant models",
     "severity": "high",
     "match": "pattern",
-    "sunset_date": "2026-10-23",
-    "date_confidence": "verify",
+    "applies_to": ["*"],
+    "sunset_date": "2025-07-14",
     "detect": {
       "sdk": ["openai"],
-      "patterns": [],
-      "models": [
-        "gpt-4o",
-        "gpt-4-turbo",
-        "gpt-4-0613",
-        "gpt-4-0125-preview",
-        "gpt-4-1106-preview",
-        "gpt-4-32k",
-        "gpt-4-vision-preview",
-        "o4-mini",
-        "gpt-4.5-preview"
-      ]
+      "models": ["gpt-4-vision-preview", "gpt-4-32k", "gpt-4.5-preview"]
     },
     "migration_url": "https://platform.openai.com/docs/deprecations",
-    "summary": "The GPT-4 family (gpt-4o snapshots, gpt-4-turbo, gpt-4-0613, o4-mini, etc.) is reported on a single API shutdown date of Oct 23, 2026; calls will then fail. Migrate to the GPT-5 family. VERIFY exact date and model membership on the official deprecations page before shipping.",
-    "source": "https://platform.openai.com/docs/deprecations"
+    "summary": "These GPT-4 variant/preview models are already retired from the API and return errors: gpt-4-vision-preview (~Dec 2024), gpt-4-32k (~mid-2025), gpt-4.5-preview (July 14, 2025). Migrate to gpt-4.1 or the GPT-5 family.",
+    "source": "https://developers.openai.com/api/docs/deprecations"
   },
   {
     "id": "openai-legacy-retired-models",
@@ -149,6 +149,7 @@
     "title": "Retired legacy OpenAI models (GPT-3 era, early snapshots)",
     "severity": "high",
     "match": "pattern",
+    "applies_to": ["*"],
     "sunset_date": "2024-01-04",
     "detect": {
       "sdk": ["openai"],
@@ -174,6 +175,7 @@
     "title": "Removed legacy Stripe.js methods",
     "severity": "high",
     "match": "pattern",
+    "applies_to": ["js", "ts", "jsx", "tsx", "mjs"],
     "sunset_date": "2026-03-25",
     "detect": {
       "sdk": ["@stripe/stripe-js", "stripe"],
@@ -197,6 +199,7 @@
     "title": "Sources API / legacy Charges API",
     "severity": "medium",
     "match": "pattern",
+    "applies_to": ["js", "ts", "jsx", "tsx", "mjs"],
     "sunset_date": "2024-05-15",
     "detect": {
       "sdk": ["stripe"],
@@ -212,6 +215,7 @@
     "title": "Notify API",
     "severity": "high",
     "match": "pattern",
+    "applies_to": ["py", "js", "ts", "jsx", "tsx", "mjs"],
     "sunset_date": "2027-01-31",
     "date_confidence": "verify",
     "detect": {
@@ -228,6 +232,7 @@
     "title": "Programmable Chat API",
     "severity": "high",
     "match": "pattern",
+    "applies_to": ["py", "js", "ts", "jsx", "tsx", "mjs"],
     "sunset_date": "2022-07-25",
     "detect": {
       "sdk": ["twilio", "twilio-chat"],
@@ -243,6 +248,7 @@
     "title": "AWS SDK for JavaScript v2",
     "severity": "medium",
     "match": "sdk",
+    "applies_to": ["js", "ts", "jsx", "tsx", "mjs"],
     "sunset_date": "2025-09-08",
     "detect": {
       "sdk": ["aws-sdk"],
@@ -258,6 +264,7 @@
     "title": "Legacy API keys (hapikey)",
     "severity": "high",
     "match": "pattern",
+    "applies_to": ["py", "js", "ts", "jsx", "tsx", "mjs"],
     "sunset_date": "2022-11-30",
     "detect": {
       "sdk": ["@hubspot/api-client"],
@@ -266,5 +273,87 @@
     "migration_url": "https://developers.hubspot.com/changelog/upcoming-api-key-sunset",
     "summary": "HubSpot deprecated legacy API keys (the hapikey query param) on Nov 30, 2022; requests using hapikey now fail. Migrate to Private App access tokens (Bearer auth). The eCommerce Bridge and Accounting Extension APIs were also sunset Dec 1, 2022.",
     "source": "https://developers.hubspot.com/changelog/upcoming-api-key-sunset"
+  },
+  {
+    "id": "openai-python-v0-syntax",
+    "vendor": "OpenAI",
+    "title": "Legacy openai-python v0 call syntax",
+    "severity": "high",
+    "match": "pattern",
+    "applies_to": ["py"],
+    "sunset_date": "2023-11-06",
+    "detect": {
+      "sdk": ["openai"],
+      "patterns": [
+        "openai\\.ChatCompletion",
+        "openai\\.Completion\\.create",
+        "openai\\.Embedding\\.create",
+        "openai\\.Moderation\\.create"
+      ]
+    },
+    "migration_url": "https://github.com/openai/openai-python/discussions/742",
+    "summary": "openai-python v1.0 (Nov 2023) removed module-level calls. openai.ChatCompletion/Completion/Embedding.create now raise APIRemovedInV1. Instantiate a client (client = OpenAI(); client.chat.completions.create(...)) or run `openai migrate`.",
+    "source": "https://github.com/openai/openai-python/issues/2172"
+  },
+  {
+    "id": "vercel-ai-sdk-v5-removed",
+    "vendor": "Vercel (AI SDK)",
+    "title": "AI SDK v4→v5/v6 removed APIs",
+    "severity": "medium",
+    "match": "pattern",
+    "applies_to": ["js", "ts", "jsx", "tsx", "mjs"],
+    "sunset_date": "2025-07-31",
+    "detect": {
+      "sdk": ["ai"],
+      "patterns": [
+        "from ['\"]ai/react['\"]",
+        "from ['\"]ai/openai['\"]",
+        "experimental_streamText",
+        "experimental_generateText",
+        "StreamingTextResponse"
+      ]
+    },
+    "migration_url": "https://ai-sdk.dev/docs/migration-guides/migration-guide-5-0",
+    "summary": "AI SDK v5 (Jul 2025) removed deprecated APIs: 'ai/react' → '@ai-sdk/react', experimental_streamText → streamText, StreamingTextResponse removed, useChat maxSteps removed. v6 moved provider imports ('ai/openai' → '@ai-sdk/openai').",
+    "source": "https://ai-sdk.dev/docs/migration-guides/migration-guide-5-0"
+  },
+  {
+    "id": "langchain-legacy-imports",
+    "vendor": "LangChain",
+    "title": "Legacy LangChain imports & chains",
+    "severity": "medium",
+    "match": "pattern",
+    "applies_to": ["py"],
+    "sunset_date": "2024-05-01",
+    "detect": {
+      "sdk": ["langchain"],
+      "patterns": [
+        "from langchain\\.llms import",
+        "from langchain\\.chat_models import",
+        "from langchain\\.embeddings import",
+        "initialize_agent",
+        "LLMChain"
+      ]
+    },
+    "migration_url": "https://python.langchain.com/docs/versions/v0_2/",
+    "summary": "Pre-0.2 LangChain imports are deprecated/removed: langchain.llms/chat_models/embeddings → langchain_community or provider packages (langchain_openai). LLMChain and initialize_agent are deprecated (use LCEL / create_agent; legacy moved to langchain-classic in 1.0).",
+    "source": "https://github.com/langchain-ai/langchain/discussions/19083"
+  },
+  {
+    "id": "resend-audiences-deprecated",
+    "vendor": "Resend",
+    "title": "Audiences API (deprecated in favor of Segments)",
+    "severity": "medium",
+    "match": "pattern",
+    "applies_to": ["js", "ts", "jsx", "tsx", "mjs", "py"],
+    "status": "deprecated",
+    "sunset_date": null,
+    "detect": {
+      "sdk": ["resend"],
+      "patterns": ["\\.audiences\\.", "\\.Audiences\\."]
+    },
+    "migration_url": "https://resend.com/docs/dashboard/segments/migrating-from-audiences-to-segments",
+    "summary": "Resend's Audiences API is deprecated in favor of Segments. The endpoints still work but will be removed in the future (no date announced). Migrate the audiences.* calls to the Segments API.",
+    "source": "https://resend.com/docs/api-reference/audiences/create-audience"
   }
 ]