arol-ai 0.1.0 → 0.1.2

package/README.md

@@ -35,25 +35,28 @@ arol-ai scan
 
 ```
 arol · local deprecation scan
-Scanned 128 files · 3 APIs detected
+Scanned 128 files · 1 API detected
 
-⚠ 3 deprecations found (2 high, 1 medium)
+⚠ 1 deprecation found (1 high, 0 medium, 0 low)
 
-● AWS · AWS SDK for JavaScript v2 end-of-support  HIGH
-  sunsets 2025-09-08 (passed 269 days ago)
-  The monolithic 'aws-sdk' (v2) entered maintenance mode in 2024 and reached
-  end-of-support. Migrate to the modular AWS SDK for JavaScript v3.
+● OpenAI · Assistants API (beta)  HIGH
+  sunsets 2026-08-26 (in 84 days)
+  The Assistants API beta is being removed on Aug 26, 2026; requests to
+  /v1/assistants and /v1/threads will fail. Migrate to the Responses API +
+  Conversations API.
   found in:
-    package.json → aws-sdk@^2.1400.0
-    src/storage.ts:1, 42
-  → migrate: https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/migrating-to-v3.html
+    src/agents/run.ts:42  →  beta.assistants
+    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:
 
 ```
@@ -62,20 +65,39 @@ When nothing is found:
 
 ## How detection works
 
-For every entry in the dataset, `arol-ai` runs two independent checks:
+Detection keys on **actual usage, not mere SDK presence.** Each dataset entry declares a `match` mode that decides what triggers it.
+
+### `match: "pattern"` — the default
+
+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.
+
+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.).
+
+**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`
+- 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"`
+
+Flags when a `detect.sdk` package appears in a manifest, **regardless of code** — for the rare "this whole SDK / version line is end-of-life" case.
 
-1. **Manifest scan** — parses the repo's root manifests for declared dependencies and their versions:
-   - `package.json` (`dependencies`, `devDependencies`, `peerDependencies`, `optionalDependencies`, plus simple npm `workspaces`)
-   - `requirements.txt` (Python)
-   - `go.mod` (Go)
+### `match: "version"`
 
-   A dependency matches if its name equals one of the entry's `detect.sdk` names (case-insensitively, with PyPI-style `_ . -` normalization).
+Flags when a `detect.sdk` package appears in a manifest **and** its declared version satisfies the entry's `version_range` (e.g. `"<3.0.0"`). Semver-style compare for npm; best-effort numeric compare for pip/go. If `version_range` is omitted, it behaves like `"sdk"`. *(No version entries ship today.)*
 
-2. **Inline scan** — walks source files and regex-matches each entry's `detect.patterns`, recording the file paths and line numbers.
-   - 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`
+**Manifests parsed** (used by `sdk`/`version` modes): `package.json` (`dependencies`, `devDependencies`, `peerDependencies`, `optionalDependencies`, plus simple npm `workspaces`), `requirements.txt` (Python), and `go.mod` (Go). A dependency matches a `detect.sdk` name case-insensitively, with PyPI-style `_ . -` normalization.
 
-A deprecation is **detected** if its SDK is present **OR** any of its patterns match. Both kinds of evidence are shown in the report.
+The report cites **source code locations** for `pattern` findings, and the **manifest line** (`package.json → name@version`) for `sdk`/`version` findings.
 
 ## CLI
 
@@ -89,6 +111,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 |
@@ -110,32 +133,66 @@ All detections are **data-driven** — the bundled dataset lives at
 
 ### Schema
 
+The dataset is either a bare array of entries, or a `{ "deprecations": [ ... ] }` object. A typical `pattern` entry:
+
+```jsonc
+{
+  "id": "openai-assistants-api",    // unique, stable identifier (required)
+  "vendor": "OpenAI",               // who owns the API (required)
+  "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
+  "detect": {
+    "sdk": ["openai"],              // scope hint for "pattern"; the trigger for "sdk"/"version"
+    "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` so it only fires on a quoted model id, never on prose:
+
 ```jsonc
 {
-  "schema_version": 1,            // optional, informational
-  "updated": "2026-06-01",        // optional, informational
-  "deprecations": [
-    {
-      "id": "aws-sdk-js-v2-eos",  // unique, stable identifier (required)
-      "vendor": "AWS",            // who owns the API (required)
-      "title": "AWS SDK for JavaScript v2 end-of-support", // short headline (required)
-      "severity": "high",         // "high" | "medium" | "low" (required)
-      "sunset_date": "2025-09-08",// ISO YYYY-MM-DD, or "" if no fixed date
-      "detect": {
-        "sdk": ["aws-sdk"],       // dependency/module names to find in manifests
-        "patterns": [             // regex strings matched against source files
-          "require\\(\\s*['\"]aws-sdk['\"]\\s*\\)",
-          "from\\s+['\"]aws-sdk['\"]"
-        ]
-      },
-      "migration_url": "https://docs.aws.amazon.com/.../migrating-to-v3.html",
-      "summary": "One or two sentences explaining the change and what to do."
-    }
-  ]
+  "id": "openai-gpt4-family-shutdown",
+  "vendor": "OpenAI",
+  "title": "GPT-4 family models (API shutdown)",
+  "severity": "high",
+  "match": "pattern",
+  "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 bare top-level array (`[ { ...entry }, ... ]`) is also accepted.
+A `version` entry instead flags on the installed SDK version (no patterns needed):
+
+```jsonc
+{
+  "id": "example-sdk-v2-eol",
+  "vendor": "Example",
+  "title": "example-sdk v2 line end-of-life",
+  "severity": "medium",
+  "match": "version",
+  "version_range": "<3.0.0",        // flags only when the declared version is in range
+  "sunset_date": "",
+  "detect": { "sdk": ["example-sdk"], "patterns": [] },
+  "migration_url": "https://example.com/migrate",
+  "summary": "Upgrade example-sdk to v3+."
+}
+```
 
 ### Field reference
 
@@ -145,19 +202,24 @@ A bare top-level array (`[ { ...entry }, ... ]`) is also accepted.
 | `vendor` | string | ✓ | Displayed before the title. |
 | `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). |
+| `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. May be empty for pattern-only detection. |
-| `detect.patterns` | string[] | – | **JSON-escaped** regular-expression strings (so `\d` becomes `\\d`). Matched per source file; invalid regexes are skipped safely. May be empty for manifest-only detection. |
+| `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. |
 | `migration_url` | string | – | Link shown in the report. |
 | `summary` | string | – | One or two sentences of guidance. |
 
-> An entry with **both** `detect.sdk` and `detect.patterns` empty can never match and is ignored.
+> 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
 
-- Patterns are matched **case-sensitively** with the global flag over each file's contents; line numbers are reported.
-- Escape backslashes for JSON: a regex `\bimport\b` is written `"\\bimport\\b"`.
-- Prefer specific anchors (`require\(\s*['"]name['"]\s*\)`, `from\s+['"]name['"]`) over bare package names to avoid false positives.
+- **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.
+- 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)
@@ -103,6 +110,7 @@ function runScan(targetPath, opts) {
                 vendor: f.deprecation.vendor,
                 title: f.deprecation.title,
                 severity: f.deprecation.severity,
+                match: f.deprecation.match,
                 sunset_date: f.deprecation.sunset_date,
                 migration_url: f.deprecation.migration_url,
                 summary: f.deprecation.summary,
@@ -141,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

@@ -37,6 +37,7 @@ exports.loadDeprecations = loadDeprecations;
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 const SEVERITIES = ["high", "medium", "low"];
+const MATCH_MODES = ["pattern", "sdk", "version"];
 /**
  * Locate the bundled deprecations.json. Tries several candidate locations so the
  * tool works both when running the compiled output (dist/) from a published
@@ -80,16 +81,29 @@ function coerceDeprecation(raw) {
     const detect = r.detect;
     const sdk = detect && isStringArray(detect.sdk) ? detect.sdk : [];
     const patterns = detect && isStringArray(detect.patterns) ? detect.patterns : [];
-    // An entry with neither SDKs nor patterns can never match — drop it.
-    if (sdk.length === 0 && patterns.length === 0)
+    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
+        : "pattern";
+    const version_range = isNonEmptyString(r.version_range)
+        ? r.version_range
+        : undefined;
+    // 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)
+        return null;
+    if ((match === "sdk" || match === "version") && sdk.length === 0)
         return null;
     return {
         id: r.id,
         vendor: r.vendor,
         title: r.title,
         severity: r.severity,
+        match,
         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

@@ -67,22 +67,24 @@ function sunsetPhrase(s, sunsetDate, now) {
     // Past or imminent sunsets are the urgent ones.
     return days <= 30 ? s.red(base + hint) : s.yellow(base + hint);
 }
-/** Group pattern matches by file into "path:line, line" summaries. */
+/** One line per source location: "path:line  →  matched text". */
 function formatPatternMatches(s, finding) {
-    const byFile = new Map();
-    for (const pm of finding.patternMatches) {
-        const arr = byFile.get(pm.file) ?? [];
-        arr.push(pm.line);
-        byFile.set(pm.file, arr);
-    }
-    const lines = [];
-    for (const [file, nums] of byFile) {
-        const uniqueSorted = Array.from(new Set(nums)).sort((a, b) => a - b);
-        const shown = uniqueSorted.slice(0, 8);
-        const more = uniqueSorted.length > shown.length
-            ? s.gray(` +${uniqueSorted.length - shown.length} more`)
-            : "";
-        lines.push(`${s.cyan(file)}${s.gray(":")}${shown.join(s.gray(", "))}${more}`);
+    // De-duplicate identical file:line:text triples and order by file then line.
+    const seen = new Set();
+    const items = finding.patternMatches.filter((pm) => {
+        const key = `${pm.file}:${pm.line}:${pm.text}`;
+        if (seen.has(key))
+            return false;
+        seen.add(key);
+        return true;
+    });
+    items.sort((a, b) => a.file.localeCompare(b.file) || a.line - b.line);
+    const MAX = 12;
+    const shown = items.slice(0, MAX);
+    const lines = shown.map((pm) => `${s.cyan(pm.file)}${s.gray(":")}${pm.line}  ${s.gray("→")}  ${pm.text}`);
+    const extra = items.length - shown.length;
+    if (extra > 0) {
+        lines.push(s.gray(`+${extra} more location${extra === 1 ? "" : "s"}`));
     }
     return lines;
 }
@@ -112,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.
@@ -154,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,6 +112,15 @@ function compileDeprecations(deprecations) {
                 // A malformed pattern in the dataset must not crash the scan.
             }
         }
+        // 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.
+            }
+        }
         return { deprecation, regexes };
     });
 }
@@ -133,9 +171,9 @@ function scanContent(content, relPath, compiled, sink) {
                 if (seenLines.has(line))
                     continue; // one record per line per pattern
                 seenLines.add(line);
-                const lineStart = lineStarts[line - 1];
-                const nextStart = line < lineStarts.length ? lineStarts[line] : content.length;
-                const text = content.slice(lineStart, nextStart).replace(/\r?\n$/, "").trim();
+                // 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 = [];
                     sink.set(deprecation.id, recorded);
@@ -171,18 +209,121 @@ function matchManifests(deprecations, refs) {
     }
     return byId;
 }
+/** Best-effort parse of a dotted numeric version from a declared string. */
+function parseVersionNumbers(raw) {
+    if (!raw)
+        return null;
+    // Pull the first dotted-number run, ignoring ^ ~ >= <= operators and a "v" prefix.
+    const m = /(\d+(?:\.\d+)*)/.exec(raw);
+    if (!m)
+        return null;
+    return m[1].split(".").map((n) => parseInt(n, 10));
+}
+function compareVersions(a, b) {
+    const len = Math.max(a.length, b.length);
+    for (let i = 0; i < len; i++) {
+        const x = a[i] ?? 0;
+        const y = b[i] ?? 0;
+        if (x !== y)
+            return x < y ? -1 : 1;
+    }
+    return 0;
+}
+/**
+ * Best-effort check that a declared version satisfies a simple range such as
+ * "<3.0.0", ">=1.2.0", or "=2.1.0" / "2.1.0". Semver-ish: compares dotted numbers.
+ * Returns true when no range is given; false when a range is required but the
+ * declared version can't be parsed (stay conservative — don't over-flag).
+ */
+function versionInRange(declared, range) {
+    if (!range)
+        return true; // no constraint → presence already established by caller
+    const rm = /^\s*(<=|>=|<|>|={1,3})?\s*v?(\d+(?:\.\d+)*)\s*$/.exec(range);
+    if (!rm)
+        return true; // unparseable range → don't invent a false constraint
+    const op = rm[1] || "=";
+    const target = rm[2].split(".").map((n) => parseInt(n, 10));
+    const have = parseVersionNumbers(declared);
+    if (!have)
+        return false;
+    const cmp = compareVersions(have, target);
+    switch (op) {
+        case "<":
+            return cmp < 0;
+        case "<=":
+            return cmp <= 0;
+        case ">":
+            return cmp > 0;
+        case ">=":
+            return cmp >= 0;
+        default:
+            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);
-    // 1. Manifest scan.
+    // 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");
+    const manifestDeps = deprecations.filter((d) => d.match === "sdk" || d.match === "version");
+    // 1. Manifest scan (drives sdk/version entries; also lists the manifests read).
     const { refs, manifests } = (0, manifests_1.collectManifestDeps)(absRoot);
-    const manifestMatches = matchManifests(deprecations, refs);
-    // 2. Inline scan.
-    const compiled = compileDeprecations(deprecations);
+    const manifestMatches = matchManifests(manifestDeps, refs);
+    // 2. Inline source scan (drives pattern entries — usage, not mere presence).
+    const compiled = compileDeprecations(patternDeps);
     const patternSink = new Map();
     const files = fast_glob_1.default.sync([`**/*.{${SOURCE_EXTENSIONS.join(",")}}`], {
         cwd: absRoot,
@@ -191,7 +332,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) {
@@ -215,14 +356,30 @@ function scanRepo(root, deprecations) {
         scannedFiles++;
         scanContent(content, rel, compiled, patternSink);
     }
-    // 3. Combine: detected if a manifest match OR a pattern match exists.
+    // 3. Build findings — one per deprecation, evaluated per its match mode.
     const findings = [];
     for (const deprecation of deprecations) {
+        if (deprecation.match === "pattern") {
+            // Flag ONLY on a real source hit; manifest/SDK presence is irrelevant here.
+            const pm = patternSink.get(deprecation.id) ?? [];
+            if (pm.length === 0)
+                continue;
+            findings.push({ deprecation, manifestMatches: [], patternMatches: pm });
+            continue;
+        }
+        // "sdk" / "version": evaluate against the manifest.
         const mm = manifestMatches.get(deprecation.id) ?? [];
-        const pm = patternSink.get(deprecation.id) ?? [];
-        if (mm.length === 0 && pm.length === 0)
+        if (mm.length === 0)
+            continue;
+        if (deprecation.match === "version") {
+            const inRange = mm.filter((m) => versionInRange(m.version, deprecation.version_range));
+            if (inRange.length === 0)
+                continue;
+            findings.push({ deprecation, manifestMatches: inRange, patternMatches: [] });
             continue;
-        findings.push({ deprecation, manifestMatches: mm, patternMatches: pm });
+        }
+        // "sdk": mere presence in a manifest is enough.
+        findings.push({ deprecation, manifestMatches: mm, patternMatches: [] });
     }
     return { scannedFiles, manifestsScanned: manifests, findings };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arol-ai",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "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

@@ -4,6 +4,7 @@
     "vendor": "OpenAI",
     "title": "Assistants API (beta)",
     "severity": "high",
+    "match": "pattern",
     "sunset_date": "2026-08-26",
     "detect": {
       "sdk": ["openai"],
@@ -23,10 +24,12 @@
     "vendor": "Anthropic",
     "title": "Claude Sonnet 4 & Opus 4",
     "severity": "high",
+    "match": "pattern",
     "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",
@@ -42,15 +45,17 @@
     "vendor": "Anthropic",
     "title": "Retired Claude models (Haiku 3, 3.5/3.7 Sonnet, Claude 2.x)",
     "severity": "high",
+    "match": "pattern",
     "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"
       ]
     },
@@ -63,14 +68,12 @@
     "vendor": "Google (Gemini)",
     "title": "Gemini 2.5 Pro / Flash / Flash-Lite",
     "severity": "high",
+    "match": "pattern",
     "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.",
@@ -81,14 +84,16 @@
     "vendor": "Google (Gemini)",
     "title": "Gemini 2.0 Flash family",
     "severity": "high",
+    "match": "pattern",
     "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",
@@ -100,18 +105,166 @@
     "vendor": "Google (Gemini)",
     "title": "Gemini 1.0 / 1.5 models",
     "severity": "high",
+    "match": "pattern",
     "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",
-        "gemini-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",
+    "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",
+    "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",
+    "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",
+    "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",
+    "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",
+    "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",
+    "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",
+    "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"
   }
 ]