arol-ai 0.1.1 → 0.1.3

package/README.md

@@ -49,12 +49,14 @@ Scanned 128 files · 1 API detected
     src/agents/run.ts:88  →  beta.threads
   → migrate: https://platform.openai.com/docs/assistants/migration
 
-These are today's deprecations. New ones land constantly — get
-alerted before the next one breaks you → arol.ai
+────────────────────────────────────────────────────────────
+⚠ These break on fixed dates. Get alerted before the next one hits you → arol.ai
 ```
 
 Note the citations point at the **exact source lines that use the deprecated API**, not at the manifest. Having the `openai` package installed is not enough on its own — your code has to actually call the removed surface.
 
+The closing line is **severity-aware**: a high-severity finding gets the prominent warning above; findings with no high-severity items get `Get continuous deprecation alerts for your stack → arol.ai`; and a clean scan gets `✓ Clean today — but new deprecations land constantly. Stay covered → arol.ai`.
+
 When nothing is found:
 
 ```
@@ -67,13 +69,28 @@ Detection keys on **actual usage, not mere SDK presence.** Each dataset entry de
 
 ### `match: "pattern"` — the default
 
-Flags **only** when one of the entry's `detect.patterns` regexes matches inside a scanned **source file** — i.e. your code actually references the deprecated endpoint, method, or model string. `detect.sdk` is just a scope hint here and is **never** a trigger on its own. This is the default and covers almost everything.
+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**.
+
+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.), in a file of the right language, outside comments.
+
+**Files scanned / skipped**
 
 - Extensions scanned: `.js .mjs .cjs .jsx .ts .mts .cts .tsx .py .go`
 - Skipped directories: `node_modules`, `.git`, `dist`, `build`, `.next`, `out`, `coverage`, `.venv`, `venv`, `vendor`
-- 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` / `beta.threads` (etc.).
+- Skipped by default: `.md`, `.mdx`, `.txt` (docs/prose, where model names appear as text), plus the tool's own `deprecations.json` and `arol.config.*` / `.arolignore` files.
+- Add a **`.arolignore`** file (gitignore-style globs) at the repo root, and/or pass **`--ignore <glob>`** (repeatable) to skip more paths.
 
 ### `match: "sdk"`
 
@@ -99,6 +116,7 @@ arol-ai scan [path] [options]
 | `--json` | Output machine-readable JSON instead of the report |
 | `--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`) |
 | `-v, --version` | Print the version |
 | `-h, --help` | Show help |
@@ -129,20 +147,60 @@ 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"
+  "applies_to": ["py","js","ts","jsx","tsx","mjs"], // extensions to test; ["*"] = any
   "sunset_date": "2026-08-26",      // ISO YYYY-MM-DD, or "" if no fixed date
   "detect": {
     "sdk": ["openai"],              // scope hint for "pattern"; the trigger for "sdk"/"version"
-    "patterns": [                   // regex strings matched against source files
+    "patterns": [                   // raw regexes: identifiers, endpoints, params
       "beta\\.assistants",
       "beta\\.threads",
       "/v1/assistants"
-    ]
+    ],
+    "models": []                    // model ids matched only inside string literals
   },
   "migration_url": "https://platform.openai.com/docs/assistants/migration",
   "summary": "One or two sentences explaining the change and what to do."
 }
 ```
 
+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
+{
+  "id": "openai-gpt4-family-shutdown",
+  "vendor": "OpenAI",
+  "title": "GPT-4 family models (API shutdown)",
+  "severity": "high",
+  "match": "pattern",
+  "applies_to": ["*"],
+  "sunset_date": "2026-10-23",
+  "detect": {
+    "sdk": ["openai"],
+    "patterns": [],
+    "models": ["gpt-4o", "gpt-4-turbo", "o4-mini", "gpt-4.5-preview"]
+  },
+  "migration_url": "https://platform.openai.com/docs/deprecations",
+  "summary": "Migrate to the GPT-5 family."
+}
+```
+
+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
@@ -169,20 +227,24 @@ A `version` entry instead flags on the installed SDK version (no patterns needed
 | `title` | string | ✓ | Short headline for the finding. |
 | `severity` | `"high"` \| `"medium"` \| `"low"` | ✓ | Drives color, sort order, and `--fail-on`. |
 | `match` | `"pattern"` \| `"sdk"` \| `"version"` | – | How the entry is triggered. **Defaults to `"pattern"`** when omitted. See [How detection works](#how-detection-works). |
+| `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"*). |
 | `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** regular-expression strings (so `\d` becomes `\\d`). Matched against source-file contents; invalid regexes are skipped safely. Required (non-empty) for `match: "pattern"`. |
+| `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. |
 | `migration_url` | string | – | Link shown in the report. |
 | `summary` | string | – | One or two sentences of guidance. |
 
-> A `pattern` entry with no `patterns`, or an `sdk`/`version` entry with no `sdk`, can never fire and is dropped at load time.
+> A `pattern` entry needs at least one `detect.patterns` **or** `detect.models` entry; an `sdk`/`version` entry needs at least one `detect.sdk`. Entries that can never fire are dropped at load time.
 
-### Writing good patterns
+### 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.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.
-- Match the **deprecated surface itself** — the method/property (`beta\.assistants`), endpoint path (`/v1/threads`), or model string (`claude-opus-4-20250514`) — not the import or the package name. Importing an SDK isn't usage; calling the removed API is.
-- Escape backslashes (and literal dots) for JSON: a regex `beta\.assistants` is written `"beta\\.assistants"`.
+- 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.)
 - Avoid `^`/`$` line anchors — matching runs against the whole file, not line-by-line; use `\b` word boundaries instead.
 
 ## Development

package/dist/cli.js

@@ -62,6 +62,10 @@ function shouldUseColor(colorFlag) {
     return Boolean(process.stdout.isTTY);
 }
 const SEVERITY_RANK = { high: 3, medium: 2, low: 1 };
+/** Commander collector so --ignore can be passed multiple times. */
+function collectIgnore(value, previous) {
+    return previous.concat([value]);
+}
 function runScan(targetPath, opts) {
     const root = path.resolve(targetPath ?? ".");
     // Validate the target directory up front for a friendly error.
@@ -88,7 +92,10 @@ function runScan(targetPath, opts) {
         process.exitCode = 2;
         return;
     }
-    const result = (0, scanner_1.scanRepo)(root, deprecations);
+    const result = (0, scanner_1.scanRepo)(root, deprecations, {
+        ignore: opts.ignore,
+        dataPath: opts.data,
+    });
     if (opts.json) {
         const counts = { high: 0, medium: 0, low: 0 };
         for (const f of result.findings)
@@ -142,6 +149,7 @@ function main(argv) {
         .option("--json", "output machine-readable JSON instead of the report")
         .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")
         .action((pathArg, options) => {
         runScan(pathArg, options);

package/dist/data.js

@@ -81,6 +81,7 @@ function coerceDeprecation(raw) {
     const detect = r.detect;
     const sdk = detect && isStringArray(detect.sdk) ? detect.sdk : [];
     const patterns = detect && isStringArray(detect.patterns) ? detect.patterns : [];
+    const models = detect && isStringArray(detect.models) ? detect.models : [];
     // Default to "pattern" — detection keys on real usage, not SDK presence.
     const match = MATCH_MODES.includes(r.match)
         ? r.match
@@ -88,8 +89,14 @@ function coerceDeprecation(raw) {
     const version_range = isNonEmptyString(r.version_range)
         ? r.version_range
         : 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.
-    if (match === "pattern" && patterns.length === 0)
+    // A "pattern" entry fires on either a raw pattern OR a model-string match.
+    if (match === "pattern" && patterns.length === 0 && models.length === 0)
         return null;
     if ((match === "sdk" || match === "version") && sdk.length === 0)
         return null;
@@ -99,8 +106,9 @@ function coerceDeprecation(raw) {
         title: r.title,
         severity: r.severity,
         match,
+        applies_to,
         sunset_date: typeof r.sunset_date === "string" ? r.sunset_date : "",
-        detect: { sdk, patterns },
+        detect: { sdk, patterns, models },
         version_range,
         migration_url: typeof r.migration_url === "string" ? r.migration_url : "",
         summary: typeof r.summary === "string" ? r.summary : "",

package/dist/report.js

@@ -114,7 +114,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));
+        out.push(footer(s, findings));
         return out.join("\n");
     }
     // Severity summary.
@@ -156,15 +156,29 @@ function renderReport(result, opts) {
         }
         out.push("");
     }
-    out.push(footer(s));
+    out.push(footer(s, findings));
     return out.join("\n");
 }
-function footer(s) {
-    return [
-        s.dim("─".repeat(60)),
-        s.dim("These are today's deprecations. New ones land constantly — get"),
-        s.dim("alerted before the next one breaks you → ") + s.cyan(s.bold("arol.ai")),
-    ].join("\n");
+/** Severity-aware closing CTA, visually separated from the findings above. */
+function footer(s, findings) {
+    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));
+    }
+    return [sep, message].join("\n");
 }
 /** Soft-wrap text to a width, indenting continuation lines. */
 function wrapText(text, width, indent) {

package/dist/scanner.js

@@ -67,13 +67,42 @@ const IGNORED_DIRS = [
     "venv",
     "vendor",
 ];
+/**
+ * Files always skipped by default: documentation/prose (where model names show
+ * up as text, not code) and the tool's own dataset / config files.
+ */
+const DEFAULT_FILE_IGNORES = [
+    "**/*.md",
+    "**/*.mdx",
+    "**/*.txt",
+    "**/deprecations.json",
+    "**/.arolignore",
+    "**/arol.config.*",
+];
 /** Skip files larger than this (bytes) to keep the scan fast. */
 const MAX_FILE_BYTES = 2 * 1024 * 1024;
 /** Cap matches recorded per pattern per file to avoid pathological output. */
 const MAX_MATCHES_PER_PATTERN_PER_FILE = 50;
+/** Any of the three string-literal quote characters. */
+const QUOTE_CLASS = "['\"`]";
+/** Escape regex metacharacters in a literal model family name. */
+function escapeRegex(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+/**
+ * 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.
+ */
+function modelRegexSource(family) {
+    return `(${QUOTE_CLASS})${escapeRegex(family)}[A-Za-z0-9._-]*\\1`;
+}
 function compileDeprecations(deprecations) {
     return deprecations.map((deprecation) => {
         const regexes = [];
+        // Raw patterns — code identifiers, endpoints, params.
         for (const pattern of deprecation.detect.patterns) {
             try {
                 // Global so we can iterate every match and derive line numbers.
@@ -83,9 +112,119 @@ function compileDeprecations(deprecations) {
                 // A malformed pattern in the dataset must not crash the scan.
             }
         }
-        return { deprecation, regexes };
+        // Model names — only matched inside string literals (quote-anchored).
+        for (const family of deprecation.detect.models) {
+            try {
+                regexes.push(new RegExp(modelRegexSource(family), "g"));
+            }
+            catch {
+                // Defensive: a pathological family name must not crash the scan.
+            }
+        }
+        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];
@@ -133,8 +272,8 @@ function scanContent(content, relPath, compiled, sink) {
                 if (seenLines.has(line))
                     continue; // one record per line per pattern
                 seenLines.add(line);
-                // Cite the matched substring itself (e.g. "beta.assistants"), normalized
-                // and length-capped, so the report points at exactly what triggered.
+                // Cite the matched substring itself, normalized and length-capped, so
+                // the report points at exactly what triggered the finding.
                 const text = (m[0] ?? "").replace(/\s+/g, " ").trim().slice(0, 120);
                 if (!recorded) {
                     recorded = [];
@@ -222,13 +361,61 @@ function versionInRange(declared, range) {
             return cmp === 0;
     }
 }
+/**
+ * Convert one .arolignore line (gitignore-style) into fast-glob ignore globs.
+ * Supports comments (#), blank lines, leading "/" anchoring, and trailing "/"
+ * for directories. Negations ("!") are not supported and are skipped.
+ */
+function arolignoreLineToGlobs(rawLine) {
+    let line = rawLine.trim();
+    if (!line || line.startsWith("#") || line.startsWith("!"))
+        return [];
+    const anchored = line.startsWith("/");
+    if (anchored)
+        line = line.slice(1);
+    const isDir = line.endsWith("/");
+    if (isDir)
+        line = line.replace(/\/+$/, "");
+    if (!line)
+        return [];
+    const base = anchored ? line : `**/${line}`;
+    // A directory ignore covers its contents; a file/glob ignore covers both the
+    // entry itself and (harmlessly) anything beneath it if it is a directory.
+    return isDir ? [`${base}/**`] : [base, `${base}/**`];
+}
+/** Read and parse a repo's .arolignore file into ignore globs (empty if none). */
+function loadArolignore(root) {
+    let content;
+    try {
+        content = fs.readFileSync(path.join(root, ".arolignore"), "utf8");
+    }
+    catch {
+        return [];
+    }
+    return content.split(/\r?\n/).flatMap(arolignoreLineToGlobs);
+}
 /**
  * Scan a repository for deprecation usage.
  * @param root repo root to scan.
  * @param deprecations validated dataset entries.
+ * @param options optional ignore globs (--ignore) and custom dataset path.
  */
-function scanRepo(root, deprecations) {
+function scanRepo(root, deprecations, options = {}) {
     const absRoot = path.resolve(root);
+    // Assemble the ignore list: dirs + default file skips + .arolignore + --ignore.
+    const ignoreGlobs = [
+        ...IGNORED_DIRS.map((d) => `**/${d}/**`),
+        ...DEFAULT_FILE_IGNORES,
+        ...loadArolignore(absRoot),
+        ...(options.ignore ?? []),
+    ];
+    // Never scan the active custom dataset file, even if it lives in the tree.
+    if (options.dataPath) {
+        const relData = path.relative(absRoot, path.resolve(options.dataPath));
+        if (relData && !relData.startsWith("..") && !path.isAbsolute(relData)) {
+            ignoreGlobs.push(relData);
+        }
+    }
     // Partition by match mode: "pattern" entries key on real source usage, while
     // "sdk"/"version" entries key on the manifest.
     const patternDeps = deprecations.filter((d) => d.match === "pattern");
@@ -246,7 +433,7 @@ function scanRepo(root, deprecations) {
         dot: false,
         followSymbolicLinks: false,
         suppressErrors: true,
-        ignore: IGNORED_DIRS.map((d) => `**/${d}/**`),
+        ignore: ignoreGlobs,
     });
     let scannedFiles = 0;
     for (const rel of files) {
@@ -268,7 +455,16 @@ function scanRepo(root, deprecations) {
             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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arol-ai",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "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,10 +26,12 @@
     "title": "Claude Sonnet 4 & Opus 4",
     "severity": "high",
     "match": "pattern",
+    "applies_to": ["*"],
     "sunset_date": "2026-06-15",
     "detect": {
       "sdk": ["@anthropic-ai/sdk", "anthropic"],
-      "patterns": [
+      "patterns": [],
+      "models": [
         "claude-sonnet-4-20250514",
         "claude-opus-4-20250514",
         "claude-sonnet-4-0",
@@ -45,15 +48,17 @@
     "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"],
-      "patterns": [
+      "patterns": [],
+      "models": [
         "claude-3-haiku-20240307",
         "claude-3-5-sonnet",
         "claude-3-7-sonnet",
-        "claude-2\\.1",
-        "claude-2\\.0",
+        "claude-2.1",
+        "claude-2.0",
         "claude-instant"
       ]
     },
@@ -67,14 +72,12 @@
     "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"],
-      "patterns": [
-        "gemini-2\\.5-pro",
-        "gemini-2\\.5-flash",
-        "gemini-2\\.5-flash-lite"
-      ]
+      "patterns": [],
+      "models": ["gemini-2.5-pro", "gemini-2.5-flash", "gemini-2.5-flash-lite"]
     },
     "migration_url": "https://ai.google.dev/gemini-api/docs/deprecations",
     "summary": "Gemini 2.5 models scheduled for shutdown Oct 16, 2026 (Google states this is the earliest possible date). Migrate to Gemini 3.x.",
@@ -86,14 +89,16 @@
     "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"],
-      "patterns": [
-        "gemini-2\\.0-flash",
-        "gemini-2\\.0-flash-001",
-        "gemini-2\\.0-flash-lite",
-        "gemini-2\\.0-flash-lite-001"
+      "patterns": [],
+      "models": [
+        "gemini-2.0-flash",
+        "gemini-2.0-flash-001",
+        "gemini-2.0-flash-lite",
+        "gemini-2.0-flash-lite-001"
       ]
     },
     "migration_url": "https://ai.google.dev/gemini-api/docs/deprecations",
@@ -106,18 +111,244 @@
     "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": [
-        "gemini-1\\.5-pro",
-        "gemini-1\\.5-flash",
-        "gemini-1\\.0-pro",
+      "patterns": [],
+      "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",
+    "vendor": "OpenAI",
+    "title": "GPT-4 family models (API shutdown)",
+    "severity": "high",
+    "match": "pattern",
+    "applies_to": ["*"],
+    "sunset_date": "2026-10-23",
+    "date_confidence": "verify",
+    "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"
+      ]
+    },
+    "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"
+  },
+  {
+    "id": "openai-legacy-retired-models",
+    "vendor": "OpenAI",
+    "title": "Retired legacy OpenAI models (GPT-3 era, early snapshots)",
+    "severity": "high",
+    "match": "pattern",
+    "applies_to": ["*"],
+    "sunset_date": "2024-01-04",
+    "detect": {
+      "sdk": ["openai"],
+      "patterns": [],
+      "models": [
+        "text-davinci-003",
+        "text-davinci-002",
+        "gpt-3.5-turbo-0301",
+        "gpt-3.5-turbo-0613",
+        "gpt-4-0314",
+        "code-davinci",
+        "text-curie",
+        "text-babbage"
+      ]
+    },
+    "migration_url": "https://platform.openai.com/docs/deprecations",
+    "summary": "These legacy models (GPT-3-era completions and early dated GPT-4/3.5 snapshots) are already retired and return errors. Migrate to current models.",
+    "source": "https://platform.openai.com/docs/deprecations"
+  },
+  {
+    "id": "stripe-removed-js-methods",
+    "vendor": "Stripe",
+    "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"],
+      "patterns": [
+        "handleCardPayment",
+        "confirmPaymentIntent",
+        "handleFpxPayment",
+        "handleCardSetup",
+        "confirmSetupIntent",
+        "createSource",
+        "retrieveSource"
+      ]
+    },
+    "migration_url": "https://docs.stripe.com/changelog/dahlia/2026-03-25/remove-legacy-stripejs-methods",
+    "summary": "These legacy Stripe.js methods were removed and now throw errors. Replace handleCardPayment/confirmPaymentIntent with confirmCardPayment, handleCardSetup/confirmSetupIntent with confirmCardSetup, and migrate createSource/retrieveSource to the PaymentMethods API.",
+    "source": "https://docs.stripe.com/changelog/dahlia/2026-03-25/remove-legacy-stripejs-methods"
+  },
+  {
+    "id": "stripe-sources-charges-legacy",
+    "vendor": "Stripe",
+    "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"],
+      "patterns": ["\\.sources\\.create", "charges\\.create", "Charge\\.create"]
+    },
+    "migration_url": "https://docs.stripe.com/payments/older-apis",
+    "summary": "The Sources API is deprecated (local payment methods stopped being accepted May 15, 2024) and the Charges API is legacy. Migrate to the PaymentMethods + PaymentIntents APIs.",
+    "source": "https://docs.stripe.com/payments/older-apis"
+  },
+  {
+    "id": "twilio-notify-eol",
+    "vendor": "Twilio",
+    "title": "Notify API",
+    "severity": "high",
+    "match": "pattern",
+    "applies_to": ["py", "js", "ts", "jsx", "tsx", "mjs"],
+    "sunset_date": "2027-01-31",
+    "date_confidence": "verify",
+    "detect": {
+      "sdk": ["twilio"],
+      "patterns": ["notify\\.v1", "\\.notify\\.services", "client\\.notify"]
+    },
+    "migration_url": "https://www.twilio.com/en-us/changelog",
+    "summary": "Twilio Notify reaches end of life Jan 31, 2027; after that all Notify API requests will fail. No 1:1 replacement — rebuild with Programmable Messaging / Conversations. Verify the date against Twilio's official EOL notice.",
+    "source": "https://www.courier.com/blog/twilio-notify-end-of-life"
+  },
+  {
+    "id": "twilio-programmable-chat-retired",
+    "vendor": "Twilio",
+    "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"],
+      "patterns": ["chat\\.v2", "IpMessaging", "twilio-chat"]
+    },
+    "migration_url": "https://www.twilio.com/docs/conversations/migrating-chat-conversations",
+    "summary": "The standalone Programmable Chat API was sunset July 25, 2022 (Programmable Chat in Flex ended June 1, 2026). Migrate to the Conversations API.",
+    "source": "https://www.twilio.com/en-us/changelog/programmable-chat-end-of-life-notice"
+  },
+  {
+    "id": "aws-sdk-js-v2-eol",
+    "vendor": "AWS",
+    "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"],
+      "patterns": []
+    },
+    "migration_url": "https://aws.amazon.com/blogs/developer/announcing-end-of-support-for-aws-sdk-for-javascript-v2/",
+    "summary": "AWS SDK for JavaScript v2 (the 'aws-sdk' package) reached end-of-support Sept 8, 2025 — no more updates or security fixes. Migrate to the modular AWS SDK v3 (@aws-sdk/* packages).",
+    "source": "https://aws.amazon.com/blogs/developer/announcing-end-of-support-for-aws-sdk-for-javascript-v2/"
+  },
+  {
+    "id": "hubspot-api-key-hapikey",
+    "vendor": "HubSpot",
+    "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"],
+      "patterns": ["hapikey\\s*=", "hapiKey\\s*="]
+    },
+    "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"
   }
 ]