arol-ai 0.1.0 → 0.1.1

package/README.md

@@ -35,25 +35,26 @@ 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
 ```
 
+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.
+
 When nothing is found:
 
 ```
@@ -62,20 +63,29 @@ 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 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.
+
+- 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.).
+
+### `match: "sdk"`
 
-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)
+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.
 
-   A dependency matches if its name equals one of the entry's `detect.sdk` names (case-insensitively, with PyPI-style `_ . -` normalization).
+### `match: "version"`
 
-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`
+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.)*
 
-A deprecation is **detected** if its SDK is present **OR** any of its patterns match. Both kinds of evidence are shown in the report.
+**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.
+
+The report cites **source code locations** for `pattern` findings, and the **manifest line** (`package.json → name@version`) for `sdk`/`version` findings.
 
 ## CLI
 
@@ -110,32 +120,45 @@ 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
 {
-  "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-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": [                   // regex strings matched against source files
+      "beta\\.assistants",
+      "beta\\.threads",
+      "/v1/assistants"
+    ]
+  },
+  "migration_url": "https://platform.openai.com/docs/assistants/migration",
+  "summary": "One or two sentences explaining the change and what to do."
 }
 ```
 
-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 +168,21 @@ 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** regular-expression strings (so `\d` becomes `\\d`). Matched against source-file contents; invalid regexes are skipped safely. Required (non-empty) for `match: "pattern"`. |
 | `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 with no `patterns`, or an `sdk`/`version` entry with no `sdk`, can never fire and is dropped at load time.
 
 ### Writing good patterns
 
-- 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.
+- 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"`.
 - Avoid `^`/`$` line anchors — matching runs against the whole file, not line-by-line; use `\b` word boundaries instead.
 
 ## Development

package/dist/cli.js

@@ -103,6 +103,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,

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,27 @@ 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)
+    // 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.
+    if (match === "pattern" && patterns.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 },
+        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;
 }

package/dist/scanner.js

@@ -133,9 +133,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 (e.g. "beta.assistants"), normalized
+                // and length-capped, so the report points at exactly what triggered.
+                const text = (m[0] ?? "").replace(/\s+/g, " ").trim().slice(0, 120);
                 if (!recorded) {
                     recorded = [];
                     sink.set(deprecation.id, recorded);
@@ -171,6 +171,57 @@ 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;
+    }
+}
 /**
  * Scan a repository for deprecation usage.
  * @param root repo root to scan.
@@ -178,11 +229,15 @@ function matchManifests(deprecations, refs) {
  */
 function scanRepo(root, deprecations) {
     const absRoot = path.resolve(root);
-    // 1. Manifest scan.
+    // 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,
@@ -215,14 +270,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;
-        findings.push({ deprecation, manifestMatches: mm, patternMatches: pm });
+        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;
+        }
+        // "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.1",
   "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,6 +24,7 @@
     "vendor": "Anthropic",
     "title": "Claude Sonnet 4 & Opus 4",
     "severity": "high",
+    "match": "pattern",
     "sunset_date": "2026-06-15",
     "detect": {
       "sdk": ["@anthropic-ai/sdk", "anthropic"],
@@ -42,6 +44,7 @@
     "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"],
@@ -63,6 +66,7 @@
     "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"],
@@ -81,6 +85,7 @@
     "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"],
@@ -100,6 +105,7 @@
     "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"],