arol-ai 0.1.0

package/README.md

@@ -0,0 +1,190 @@
+# arol-ai
+
+Scan a local code repo for usage of third-party APIs/SDKs that have **upcoming deprecations**, and print a clean report.
+
+**Everything runs locally.** No network calls, no telemetry, no uploads, no auth. Your code never leaves your machine.
+
+```
+npx arol-ai scan
+```
+
+---
+
+## Quick start
+
+Scan the current directory:
+
+```sh
+npx arol-ai scan
+```
+
+Scan a specific path:
+
+```sh
+npx arol-ai scan ./path/to/repo
+```
+
+Install globally (optional):
+
+```sh
+npm install -g arol-ai
+arol-ai scan
+```
+
+## Example output
+
+```
+arol · local deprecation scan
+Scanned 128 files · 3 APIs detected
+
+⚠ 3 deprecations found (2 high, 1 medium)
+
+● 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.
+  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
+
+...
+
+These are today's deprecations. New ones land constantly — get
+alerted before the next one breaks you → arol.ai
+```
+
+When nothing is found:
+
+```
+✓ No upcoming deprecations detected in your stack.
+```
+
+## How detection works
+
+For every entry in the dataset, `arol-ai` runs two independent checks:
+
+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)
+
+   A dependency matches if its name equals one of the entry's `detect.sdk` names (case-insensitively, with PyPI-style `_ . -` normalization).
+
+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`
+
+A deprecation is **detected** if its SDK is present **OR** any of its patterns match. Both kinds of evidence are shown in the report.
+
+## CLI
+
+```
+arol-ai scan [path] [options]
+```
+
+| Option | Description |
+| --- | --- |
+| `[path]` | Directory to scan (default: `.`) |
+| `--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 |
+| `--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 |
+
+`scan` is the default command, so `arol-ai ./repo` works too.
+
+**Exit codes:** `0` success · `1` `--fail-on` threshold met · `2` bad path or dataset error. The `--fail-on` flag makes `arol-ai` useful as a CI gate:
+
+```sh
+npx arol-ai scan --fail-on high
+```
+
+Colors are automatically disabled when output is not a TTY (e.g. piped to a file), or when `NO_COLOR` is set. Use `FORCE_COLOR=1` to force them on.
+
+## The dataset (`deprecations.json`)
+
+All detections are **data-driven** — the bundled dataset lives at
+[`src/data/deprecations.json`](src/data/deprecations.json) and can be extended **without changing any code**. Add an entry and re-run; or keep your own file and pass it with `--data ./my-deprecations.json`.
+
+### Schema
+
+```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."
+    }
+  ]
+}
+```
+
+A bare top-level array (`[ { ...entry }, ... ]`) is also accepted.
+
+### Field reference
+
+| Field | Type | Required | Notes |
+| --- | --- | --- | --- |
+| `id` | string | ✓ | Unique, stable slug. |
+| `vendor` | string | ✓ | Displayed before the title. |
+| `title` | string | ✓ | Short headline for the finding. |
+| `severity` | `"high"` \| `"medium"` \| `"low"` | ✓ | Drives color, sort order, and `--fail-on`. |
+| `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. |
+| `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.
+
+### 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.
+- Avoid `^`/`$` line anchors — matching runs against the whole file, not line-by-line; use `\b` word boundaries instead.
+
+## Development
+
+```sh
+npm install
+npm run build          # tsc -> dist/
+node dist/cli.js scan ./some/repo
+npm run scan -- ./some/repo
+```
+
+Source layout:
+
+| File | Responsibility |
+| --- | --- |
+| `src/cli.ts` | Argument parsing (`commander`), output mode, exit codes |
+| `src/scanner.ts` | Orchestrates manifest + inline scans, combines findings |
+| `src/manifests.ts` | Parsers for `package.json`, `requirements.txt`, `go.mod` |
+| `src/report.ts` | Colorized terminal report rendering |
+| `src/data.ts` | Loads & validates the dataset |
+| `src/data/deprecations.json` | The bundled, extensible dataset |
+| `src/types.ts` | Shared type definitions |
+
+## Privacy
+
+`arol-ai` makes **zero** network requests. It reads files under the path you point it at, matches them against a local JSON dataset, and prints to your terminal. Nothing is uploaded, logged remotely, or phoned home.
+
+## License
+
+MIT

package/dist/cli.js

@@ -0,0 +1,150 @@
+#!/usr/bin/env node
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const commander_1 = require("commander");
+const data_1 = require("./data");
+const scanner_1 = require("./scanner");
+const report_1 = require("./report");
+/** Read this package's version without importing across the rootDir boundary. */
+function readVersion() {
+    try {
+        const pkgPath = path.join(__dirname, "..", "package.json");
+        const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf8"));
+        return typeof pkg.version === "string" ? pkg.version : "0.0.0";
+    }
+    catch {
+        return "0.0.0";
+    }
+}
+function shouldUseColor(colorFlag) {
+    // commander sets colorFlag=false when --no-color is passed.
+    if (!colorFlag)
+        return false;
+    if (process.env.NO_COLOR)
+        return false;
+    if (process.env.FORCE_COLOR && process.env.FORCE_COLOR !== "0")
+        return true;
+    return Boolean(process.stdout.isTTY);
+}
+const SEVERITY_RANK = { high: 3, medium: 2, low: 1 };
+function runScan(targetPath, opts) {
+    const root = path.resolve(targetPath ?? ".");
+    // Validate the target directory up front for a friendly error.
+    let stat;
+    try {
+        stat = fs.statSync(root);
+    }
+    catch {
+        process.stderr.write(`arol: path not found: ${root}\n`);
+        process.exitCode = 2;
+        return;
+    }
+    if (!stat.isDirectory()) {
+        process.stderr.write(`arol: not a directory: ${root}\n`);
+        process.exitCode = 2;
+        return;
+    }
+    let deprecations;
+    try {
+        deprecations = (0, data_1.loadDeprecations)(opts.data);
+    }
+    catch (err) {
+        process.stderr.write(`arol: ${err.message}\n`);
+        process.exitCode = 2;
+        return;
+    }
+    const result = (0, scanner_1.scanRepo)(root, deprecations);
+    if (opts.json) {
+        const counts = { high: 0, medium: 0, low: 0 };
+        for (const f of result.findings)
+            counts[f.deprecation.severity]++;
+        const payload = {
+            scannedFiles: result.scannedFiles,
+            manifestsScanned: result.manifestsScanned,
+            detected: result.findings.length,
+            counts,
+            findings: result.findings.map((f) => ({
+                id: f.deprecation.id,
+                vendor: f.deprecation.vendor,
+                title: f.deprecation.title,
+                severity: f.deprecation.severity,
+                sunset_date: f.deprecation.sunset_date,
+                migration_url: f.deprecation.migration_url,
+                summary: f.deprecation.summary,
+                manifestMatches: f.manifestMatches,
+                patternMatches: f.patternMatches,
+            })),
+        };
+        process.stdout.write(JSON.stringify(payload, null, 2) + "\n");
+    }
+    else {
+        const report = (0, report_1.renderReport)(result, { color: shouldUseColor(opts.color) });
+        process.stdout.write(report + "\n");
+    }
+    // Optional CI gate: exit non-zero if a finding meets/exceeds the threshold.
+    const failOn = opts.failOn?.toLowerCase();
+    if (failOn && failOn !== "none") {
+        const threshold = failOn === "any"
+            ? 1
+            : SEVERITY_RANK[failOn] ?? Number.POSITIVE_INFINITY;
+        const tripped = result.findings.some((f) => SEVERITY_RANK[f.deprecation.severity] >= threshold);
+        if (tripped)
+            process.exitCode = 1;
+    }
+}
+function main(argv) {
+    const program = new commander_1.Command();
+    program
+        .name("arol-ai")
+        .description("Scan a local repo for upcoming third-party API/SDK deprecations.\n" +
+        "Everything runs locally — no network, no telemetry, your code never leaves the machine.")
+        .version(readVersion(), "-v, --version", "print the arol-ai version");
+    program
+        .command("scan", { isDefault: true })
+        .argument("[path]", "directory to scan", ".")
+        .description("scan a repository and print a deprecation report")
+        .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("--fail-on <severity>", "exit non-zero if findings meet this level: high | medium | low | any | none", "none")
+        .action((pathArg, options) => {
+        runScan(pathArg, options);
+    });
+    program.parse(argv);
+}
+main(process.argv);

package/dist/data.js

@@ -0,0 +1,131 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadDeprecations = loadDeprecations;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const SEVERITIES = ["high", "medium", "low"];
+/**
+ * Locate the bundled deprecations.json. Tries several candidate locations so the
+ * tool works both when running the compiled output (dist/) from a published
+ * package and when running straight from source.
+ */
+function defaultDataPath() {
+    const candidates = [
+        // Copied alongside compiled output (if a build step does so).
+        path.join(__dirname, "data", "deprecations.json"),
+        // Published layout: dist/data.js resolving back up to src/data/.
+        path.join(__dirname, "..", "src", "data", "deprecations.json"),
+        // Running directly from src/ (e.g. ts-node).
+        path.join(__dirname, "..", "data", "deprecations.json"),
+    ];
+    for (const candidate of candidates) {
+        if (fs.existsSync(candidate))
+            return candidate;
+    }
+    // Fall back to the first candidate so the error message is meaningful.
+    return candidates[0];
+}
+function isNonEmptyString(value) {
+    return typeof value === "string" && value.length > 0;
+}
+function isStringArray(value) {
+    return Array.isArray(value) && value.every((v) => typeof v === "string");
+}
+/** Validate and normalize a single raw entry, or return null if it is malformed. */
+function coerceDeprecation(raw) {
+    if (typeof raw !== "object" || raw === null)
+        return null;
+    const r = raw;
+    if (!isNonEmptyString(r.id))
+        return null;
+    if (!isNonEmptyString(r.vendor))
+        return null;
+    if (!isNonEmptyString(r.title))
+        return null;
+    if (!SEVERITIES.includes(r.severity))
+        return null;
+    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)
+        return null;
+    return {
+        id: r.id,
+        vendor: r.vendor,
+        title: r.title,
+        severity: r.severity,
+        sunset_date: typeof r.sunset_date === "string" ? r.sunset_date : "",
+        detect: { sdk, patterns },
+        migration_url: typeof r.migration_url === "string" ? r.migration_url : "",
+        summary: typeof r.summary === "string" ? r.summary : "",
+    };
+}
+/**
+ * Load and validate the deprecations dataset.
+ * @param customPath optional path to an alternative dataset file.
+ */
+function loadDeprecations(customPath) {
+    const file = customPath ? path.resolve(customPath) : defaultDataPath();
+    let contents;
+    try {
+        contents = fs.readFileSync(file, "utf8");
+    }
+    catch {
+        throw new Error(`Could not read deprecations dataset at: ${file}`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(contents);
+    }
+    catch (err) {
+        throw new Error(`deprecations dataset is not valid JSON (${file}): ${err.message}`);
+    }
+    // Accept either the full { deprecations: [...] } shape or a bare array.
+    const rawList = Array.isArray(parsed)
+        ? parsed
+        : parsed?.deprecations;
+    if (!Array.isArray(rawList)) {
+        throw new Error(`deprecations dataset must contain a "deprecations" array (${file}).`);
+    }
+    const deprecations = [];
+    for (const raw of rawList) {
+        const entry = coerceDeprecation(raw);
+        if (entry)
+            deprecations.push(entry);
+    }
+    return deprecations;
+}

package/dist/manifests.js

@@ -0,0 +1,227 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeName = normalizeName;
+exports.nameMatches = nameMatches;
+exports.parsePackageJson = parsePackageJson;
+exports.packageJsonWorkspaces = packageJsonWorkspaces;
+exports.parseRequirements = parseRequirements;
+exports.parseGoMod = parseGoMod;
+exports.collectManifestDeps = collectManifestDeps;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const fast_glob_1 = __importDefault(require("fast-glob"));
+/**
+ * Normalize a name for tolerant comparison. PyPI treats runs of `_ . -` as
+ * equivalent and is case-insensitive; npm names are lowercase; Go module paths
+ * keep their slashes (untouched here) so identical paths still compare equal.
+ */
+function normalizeName(name) {
+    return name.toLowerCase().replace(/[_.-]+/g, "-");
+}
+/** True if a manifest dependency name matches one of a deprecation's SDK names. */
+function nameMatches(sdk, depName) {
+    if (sdk.toLowerCase() === depName.toLowerCase())
+        return true;
+    return normalizeName(sdk) === normalizeName(depName);
+}
+function readFileSafe(file) {
+    try {
+        return fs.readFileSync(file, "utf8");
+    }
+    catch {
+        return null;
+    }
+}
+const PACKAGE_JSON_DEP_FIELDS = [
+    "dependencies",
+    "devDependencies",
+    "peerDependencies",
+    "optionalDependencies",
+];
+/** Parse a package.json's dependency maps into PkgRefs. */
+function parsePackageJson(content, source) {
+    const refs = [];
+    let json;
+    try {
+        json = JSON.parse(content);
+    }
+    catch {
+        return refs;
+    }
+    for (const field of PACKAGE_JSON_DEP_FIELDS) {
+        const deps = json[field];
+        if (typeof deps !== "object" || deps === null)
+            continue;
+        for (const [name, version] of Object.entries(deps)) {
+            refs.push({
+                name,
+                version: typeof version === "string" ? version : null,
+                source,
+            });
+        }
+    }
+    return refs;
+}
+/** Extract workspace glob patterns from a root package.json, if any. */
+function packageJsonWorkspaces(content) {
+    try {
+        const json = JSON.parse(content);
+        const ws = json.workspaces;
+        if (Array.isArray(ws))
+            return ws.filter((w) => typeof w === "string");
+        if (ws && typeof ws === "object") {
+            const packages = ws.packages;
+            if (Array.isArray(packages)) {
+                return packages.filter((w) => typeof w === "string");
+            }
+        }
+    }
+    catch {
+        /* ignore */
+    }
+    return [];
+}
+/** Parse a requirements.txt into PkgRefs. */
+function parseRequirements(content, source) {
+    const refs = [];
+    // name, optional [extras], optional (operator + version).
+    const lineRe = /^([A-Za-z0-9][A-Za-z0-9._-]*)\s*(?:\[[^\]]*\])?\s*((?:==|===|>=|<=|~=|!=|<|>)\s*[^\s;#]+)?/;
+    for (const rawLine of content.split(/\r?\n/)) {
+        // Strip inline comments and surrounding whitespace.
+        let line = rawLine.replace(/\s+#.*$/, "").trim();
+        if (!line || line.startsWith("#"))
+            continue;
+        // Skip pip options (-r, -e, --hash, ...) and direct URLs / VCS installs.
+        if (line.startsWith("-"))
+            continue;
+        if (/^[a-z+]+:\/\//i.test(line) || line.includes("@ "))
+            continue;
+        const m = lineRe.exec(line);
+        if (!m)
+            continue;
+        const name = m[1];
+        const version = m[2] ? m[2].replace(/\s+/g, "") : null;
+        refs.push({ name, version, source });
+    }
+    return refs;
+}
+/** Parse a go.mod file's require directives into PkgRefs. */
+function parseGoMod(content, source) {
+    const refs = [];
+    const lines = content.split(/\r?\n/);
+    let inBlock = false;
+    const pushModule = (modPart) => {
+        // modPart looks like: "github.com/foo/bar v1.2.3 // indirect"
+        const cleaned = modPart.replace(/\/\/.*$/, "").trim();
+        if (!cleaned)
+            return;
+        const parts = cleaned.split(/\s+/);
+        if (parts.length < 2)
+            return;
+        refs.push({ name: parts[0], version: parts[1], source });
+    };
+    for (const rawLine of lines) {
+        const line = rawLine.trim();
+        if (!line)
+            continue;
+        if (inBlock) {
+            if (line.startsWith(")")) {
+                inBlock = false;
+                continue;
+            }
+            pushModule(line);
+            continue;
+        }
+        if (/^require\s*\(\s*$/.test(line)) {
+            inBlock = true;
+            continue;
+        }
+        const single = /^require\s+(.+)$/.exec(line);
+        if (single)
+            pushModule(single[1]);
+    }
+    return refs;
+}
+/**
+ * Collect every dependency declared in the repo's root manifests
+ * (package.json, requirements.txt, go.mod) plus simple npm workspaces.
+ * Returns the dependency refs and the list of manifest files that were read.
+ */
+function collectManifestDeps(root) {
+    const refs = [];
+    const manifests = [];
+    const addManifest = (absPath, parse) => {
+        const content = readFileSafe(absPath);
+        if (content === null)
+            return content;
+        const rel = path.relative(root, absPath) || path.basename(absPath);
+        manifests.push(rel);
+        refs.push(...parse(content, rel));
+        return content;
+    };
+    // Root package.json (+ workspaces).
+    const rootPkgPath = path.join(root, "package.json");
+    const rootPkgContent = addManifest(rootPkgPath, parsePackageJson);
+    if (rootPkgContent) {
+        const patterns = packageJsonWorkspaces(rootPkgContent);
+        if (patterns.length > 0) {
+            let wsPkgPaths = [];
+            try {
+                wsPkgPaths = fast_glob_1.default.sync(patterns.map((p) => `${p.replace(/\/+$/, "")}/package.json`), {
+                    cwd: root,
+                    absolute: true,
+                    ignore: ["**/node_modules/**"],
+                    suppressErrors: true,
+                });
+            }
+            catch {
+                wsPkgPaths = [];
+            }
+            for (const wsPath of wsPkgPaths) {
+                if (path.resolve(wsPath) === path.resolve(rootPkgPath))
+                    continue;
+                addManifest(wsPath, parsePackageJson);
+            }
+        }
+    }
+    // Python and Go root manifests.
+    addManifest(path.join(root, "requirements.txt"), parseRequirements);
+    addManifest(path.join(root, "go.mod"), parseGoMod);
+    return { refs, manifests };
+}

package/dist/report.js

@@ -0,0 +1,184 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.renderReport = renderReport;
+function makeStyler(enabled) {
+    const wrap = (open, close) => (s) => enabled ? `\x1b[${open}m${s}\x1b[${close}m` : s;
+    return {
+        enabled,
+        bold: wrap(1, 22),
+        dim: wrap(2, 22),
+        underline: wrap(4, 24),
+        red: wrap(31, 39),
+        green: wrap(32, 39),
+        yellow: wrap(33, 39),
+        blue: wrap(34, 39),
+        cyan: wrap(36, 39),
+        gray: wrap(90, 39),
+        white: wrap(97, 39),
+        black: wrap(30, 39),
+        bgRed: wrap(41, 49),
+        bgYellow: wrap(43, 49),
+        bgBlue: wrap(44, 49),
+    };
+}
+const SEVERITY_ORDER = { high: 0, medium: 1, low: 2 };
+function severityColor(s, sev) {
+    if (sev === "high")
+        return s.red;
+    if (sev === "medium")
+        return s.yellow;
+    return s.blue;
+}
+/** A colored pill like ` HIGH `. */
+function severityPill(s, sev) {
+    const label = ` ${sev.toUpperCase()} `;
+    if (!s.enabled)
+        return `[${sev.toUpperCase()}]`;
+    if (sev === "high")
+        return s.bgRed(s.white(s.bold(label)));
+    if (sev === "medium")
+        return s.bgYellow(s.black(s.bold(label)));
+    return s.bgBlue(s.white(s.bold(label)));
+}
+/** Render the sunset date with a relative hint, or a note when there is no date. */
+function sunsetPhrase(s, sunsetDate, now) {
+    if (!sunsetDate) {
+        return s.gray("no fixed sunset date — already deprecated / unmaintained");
+    }
+    const parsed = new Date(`${sunsetDate}T00:00:00Z`);
+    if (Number.isNaN(parsed.getTime())) {
+        return s.gray(`sunsets ${sunsetDate}`);
+    }
+    const msPerDay = 24 * 60 * 60 * 1000;
+    const days = Math.round((parsed.getTime() - now.getTime()) / msPerDay);
+    let rel;
+    if (days > 1)
+        rel = `in ${days} days`;
+    else if (days === 1)
+        rel = "in 1 day";
+    else if (days === 0)
+        rel = "today";
+    else if (days === -1)
+        rel = "1 day ago";
+    else
+        rel = `${Math.abs(days)} days ago`;
+    const base = `sunsets ${sunsetDate}`;
+    const hint = days <= 0 ? ` (passed ${rel})` : ` (${rel})`;
+    // Past or imminent sunsets are the urgent ones.
+    return days <= 30 ? s.red(base + hint) : s.yellow(base + hint);
+}
+/** Group pattern matches by file into "path:line, line" summaries. */
+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}`);
+    }
+    return lines;
+}
+/** Render the full human-readable terminal report. */
+function renderReport(result, opts) {
+    const s = makeStyler(opts.color);
+    const now = opts.now ?? new Date();
+    const out = [];
+    const findings = [...result.findings].sort((a, b) => {
+        const sevDiff = SEVERITY_ORDER[a.deprecation.severity] -
+            SEVERITY_ORDER[b.deprecation.severity];
+        if (sevDiff !== 0)
+            return sevDiff;
+        // Within a severity, soonest/earliest sunset first; undated last.
+        const da = a.deprecation.sunset_date || "9999-99-99";
+        const db = b.deprecation.sunset_date || "9999-99-99";
+        return da.localeCompare(db);
+    });
+    // Header.
+    out.push("");
+    out.push(s.bold("arol") +
+        s.dim(" · local deprecation scan"));
+    const fileWord = result.scannedFiles === 1 ? "file" : "files";
+    const apiWord = findings.length === 1 ? "API" : "APIs";
+    out.push(s.gray(`Scanned ${result.scannedFiles} ${fileWord} · ${findings.length} ${apiWord} detected`));
+    out.push("");
+    if (findings.length === 0) {
+        out.push(s.green(s.bold("✓ No upcoming deprecations detected in your stack.")));
+        out.push("");
+        out.push(footer(s));
+        return out.join("\n");
+    }
+    // Severity summary.
+    const counts = { high: 0, medium: 0, low: 0 };
+    for (const f of findings)
+        counts[f.deprecation.severity]++;
+    const summaryParts = [
+        s.red(`${counts.high} high`),
+        s.yellow(`${counts.medium} medium`),
+        s.blue(`${counts.low} low`),
+    ];
+    const noun = findings.length === 1 ? "deprecation" : "deprecations";
+    out.push(s.bold(s.yellow("⚠ ")) +
+        s.bold(`${findings.length} ${noun} found`) +
+        s.gray(` (${summaryParts.join(s.gray(", "))})`));
+    out.push("");
+    // Per finding.
+    for (const finding of findings) {
+        const d = finding.deprecation;
+        const sevColor = severityColor(s, d.severity);
+        out.push(`${sevColor("●")} ${s.bold(d.vendor)} ${s.gray("·")} ${d.title} ${severityPill(s, d.severity)}`);
+        out.push(`  ${sunsetPhrase(s, d.sunset_date, now)}`);
+        if (d.summary) {
+            out.push(`  ${s.dim(wrapText(d.summary, 76, "  ").trimStart())}`);
+        }
+        // Evidence.
+        out.push(`  ${s.gray("found in:")}`);
+        for (const mm of finding.manifestMatches) {
+            const ver = mm.version
+                ? s.gray("@") + mm.version
+                : s.gray(" (declared, no version)");
+            out.push(`    ${s.cyan(mm.manifest)} ${s.gray("→")} ${mm.sdk}${ver}`);
+        }
+        for (const line of formatPatternMatches(s, finding)) {
+            out.push(`    ${line}`);
+        }
+        if (d.migration_url) {
+            out.push(`  ${s.gray("→ migrate:")} ${s.underline(s.cyan(d.migration_url))}`);
+        }
+        out.push("");
+    }
+    out.push(footer(s));
+    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");
+}
+/** Soft-wrap text to a width, indenting continuation lines. */
+function wrapText(text, width, indent) {
+    const words = text.split(/\s+/);
+    const lines = [];
+    let current = "";
+    for (const word of words) {
+        if (current.length + word.length + 1 > width && current.length > 0) {
+            lines.push(current);
+            current = word;
+        }
+        else {
+            current = current ? `${current} ${word}` : word;
+        }
+    }
+    if (current)
+        lines.push(current);
+    return lines.map((l, i) => (i === 0 ? l : indent + l)).join("\n");
+}

package/dist/scanner.js

@@ -0,0 +1,228 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.scanRepo = scanRepo;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const fast_glob_1 = __importDefault(require("fast-glob"));
+const manifests_1 = require("./manifests");
+/** Source file extensions that get the inline regex scan. */
+const SOURCE_EXTENSIONS = [
+    "js",
+    "mjs",
+    "cjs",
+    "jsx",
+    "ts",
+    "mts",
+    "cts",
+    "tsx",
+    "py",
+    "go",
+];
+/** Directories never worth walking. */
+const IGNORED_DIRS = [
+    "node_modules",
+    ".git",
+    "dist",
+    "build",
+    ".next",
+    "out",
+    "coverage",
+    ".venv",
+    "venv",
+    "vendor",
+];
+/** 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;
+function compileDeprecations(deprecations) {
+    return deprecations.map((deprecation) => {
+        const regexes = [];
+        for (const pattern of deprecation.detect.patterns) {
+            try {
+                // Global so we can iterate every match and derive line numbers.
+                regexes.push(new RegExp(pattern, "g"));
+            }
+            catch {
+                // A malformed pattern in the dataset must not crash the scan.
+            }
+        }
+        return { deprecation, regexes };
+    });
+}
+/** Precompute the byte offset at which each line starts. */
+function computeLineStarts(content) {
+    const starts = [0];
+    for (let i = 0; i < content.length; i++) {
+        if (content.charCodeAt(i) === 10 /* \n */)
+            starts.push(i + 1);
+    }
+    return starts;
+}
+/** Map a character offset to a 1-based line number via binary search. */
+function lineNumberAt(lineStarts, offset) {
+    let lo = 0;
+    let hi = lineStarts.length - 1;
+    let ans = 0;
+    while (lo <= hi) {
+        const mid = (lo + hi) >> 1;
+        if (lineStarts[mid] <= offset) {
+            ans = mid;
+            lo = mid + 1;
+        }
+        else {
+            hi = mid - 1;
+        }
+    }
+    return ans + 1;
+}
+/** Match every compiled deprecation against one file's contents. */
+function scanContent(content, relPath, compiled, sink) {
+    const lineStarts = computeLineStarts(content);
+    for (const { deprecation, regexes } of compiled) {
+        if (regexes.length === 0)
+            continue;
+        let recorded = sink.get(deprecation.id);
+        for (const baseRe of regexes) {
+            // Use a fresh regex instance per file so lastIndex never leaks across files.
+            const re = new RegExp(baseRe.source, baseRe.flags);
+            let count = 0;
+            let m;
+            const seenLines = new Set();
+            while ((m = re.exec(content)) !== null) {
+                // Guard against zero-width matches looping forever.
+                if (m.index === re.lastIndex)
+                    re.lastIndex++;
+                const line = lineNumberAt(lineStarts, m.index);
+                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();
+                if (!recorded) {
+                    recorded = [];
+                    sink.set(deprecation.id, recorded);
+                }
+                recorded.push({ file: relPath, line, text });
+                if (++count >= MAX_MATCHES_PER_PATTERN_PER_FILE)
+                    break;
+            }
+        }
+    }
+}
+/** Find dependencies in the collected manifest refs that match each deprecation. */
+function matchManifests(deprecations, refs) {
+    const byId = new Map();
+    for (const deprecation of deprecations) {
+        if (deprecation.detect.sdk.length === 0)
+            continue;
+        const matches = [];
+        const seen = new Set();
+        for (const sdk of deprecation.detect.sdk) {
+            for (const ref of refs) {
+                if (!(0, manifests_1.nameMatches)(sdk, ref.name))
+                    continue;
+                const key = `${ref.source}::${ref.name}`;
+                if (seen.has(key))
+                    continue;
+                seen.add(key);
+                matches.push({ manifest: ref.source, sdk: ref.name, version: ref.version });
+            }
+        }
+        if (matches.length > 0)
+            byId.set(deprecation.id, matches);
+    }
+    return byId;
+}
+/**
+ * Scan a repository for deprecation usage.
+ * @param root repo root to scan.
+ * @param deprecations validated dataset entries.
+ */
+function scanRepo(root, deprecations) {
+    const absRoot = path.resolve(root);
+    // 1. Manifest scan.
+    const { refs, manifests } = (0, manifests_1.collectManifestDeps)(absRoot);
+    const manifestMatches = matchManifests(deprecations, refs);
+    // 2. Inline scan.
+    const compiled = compileDeprecations(deprecations);
+    const patternSink = new Map();
+    const files = fast_glob_1.default.sync([`**/*.{${SOURCE_EXTENSIONS.join(",")}}`], {
+        cwd: absRoot,
+        absolute: false,
+        onlyFiles: true,
+        dot: false,
+        followSymbolicLinks: false,
+        suppressErrors: true,
+        ignore: IGNORED_DIRS.map((d) => `**/${d}/**`),
+    });
+    let scannedFiles = 0;
+    for (const rel of files) {
+        const abs = path.join(absRoot, rel);
+        let stat;
+        try {
+            stat = fs.statSync(abs);
+        }
+        catch {
+            continue;
+        }
+        if (!stat.isFile() || stat.size > MAX_FILE_BYTES)
+            continue;
+        let content;
+        try {
+            content = fs.readFileSync(abs, "utf8");
+        }
+        catch {
+            continue;
+        }
+        scannedFiles++;
+        scanContent(content, rel, compiled, patternSink);
+    }
+    // 3. Combine: detected if a manifest match OR a pattern match exists.
+    const findings = [];
+    for (const deprecation of deprecations) {
+        const mm = manifestMatches.get(deprecation.id) ?? [];
+        const pm = patternSink.get(deprecation.id) ?? [];
+        if (mm.length === 0 && pm.length === 0)
+            continue;
+        findings.push({ deprecation, manifestMatches: mm, patternMatches: pm });
+    }
+    return { scannedFiles, manifestsScanned: manifests, findings };
+}

package/dist/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "arol-ai",
+  "version": "0.1.0",
+  "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",
+    "sdk",
+    "api",
+    "scanner",
+    "cli",
+    "migration",
+    "dependencies",
+    "audit"
+  ],
+  "homepage": "https://arol.ai",
+  "license": "MIT",
+  "type": "commonjs",
+  "bin": {
+    "arol-ai": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "src/data/deprecations.json",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc",
+    "scan": "node dist/cli.js scan",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "commander": "^12.1.0",
+    "fast-glob": "^3.3.2"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "typescript": "^5.7.2"
+  }
+}

package/src/data/deprecations.json

@@ -0,0 +1,117 @@
+[
+  {
+    "id": "openai-assistants-api",
+    "vendor": "OpenAI",
+    "title": "Assistants API (beta)",
+    "severity": "high",
+    "sunset_date": "2026-08-26",
+    "detect": {
+      "sdk": ["openai"],
+      "patterns": [
+        "beta\\.assistants",
+        "beta\\.threads",
+        "/v1/assistants",
+        "/v1/threads"
+      ]
+    },
+    "migration_url": "https://platform.openai.com/docs/assistants/migration",
+    "summary": "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.",
+    "source": "https://developers.openai.com/api/docs/deprecations"
+  },
+  {
+    "id": "anthropic-claude-4-retirement",
+    "vendor": "Anthropic",
+    "title": "Claude Sonnet 4 & Opus 4",
+    "severity": "high",
+    "sunset_date": "2026-06-15",
+    "detect": {
+      "sdk": ["@anthropic-ai/sdk", "anthropic"],
+      "patterns": [
+        "claude-sonnet-4-20250514",
+        "claude-opus-4-20250514",
+        "claude-sonnet-4-0",
+        "claude-opus-4-0"
+      ]
+    },
+    "migration_url": "https://platform.claude.com/docs/en/about-claude/model-deprecations",
+    "summary": "Claude Sonnet 4 and Opus 4 retire June 15, 2026; calls to these model IDs will fail. Migrate to Sonnet 4.6 / Opus 4.6.",
+    "source": "https://platform.claude.com/docs/en/release-notes/overview"
+  },
+  {
+    "id": "anthropic-retired-legacy-claude",
+    "vendor": "Anthropic",
+    "title": "Retired Claude models (Haiku 3, 3.5/3.7 Sonnet, Claude 2.x)",
+    "severity": "high",
+    "sunset_date": "2026-04-20",
+    "detect": {
+      "sdk": ["@anthropic-ai/sdk", "anthropic"],
+      "patterns": [
+        "claude-3-haiku-20240307",
+        "claude-3-5-sonnet",
+        "claude-3-7-sonnet",
+        "claude-2\\.1",
+        "claude-2\\.0",
+        "claude-instant"
+      ]
+    },
+    "migration_url": "https://platform.claude.com/docs/en/about-claude/model-deprecations",
+    "summary": "These Claude model IDs are already retired and return errors. Migrate to current models (Haiku 4.5 / Sonnet 4.6 / Opus 4.6).",
+    "source": "https://platform.claude.com/docs/en/about-claude/model-deprecations"
+  },
+  {
+    "id": "google-gemini-2-5-retirement",
+    "vendor": "Google (Gemini)",
+    "title": "Gemini 2.5 Pro / Flash / Flash-Lite",
+    "severity": "high",
+    "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"
+      ]
+    },
+    "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.",
+    "source": "https://ai.google.dev/gemini-api/docs/deprecations"
+  },
+  {
+    "id": "google-gemini-2-0-shutdown",
+    "vendor": "Google (Gemini)",
+    "title": "Gemini 2.0 Flash family",
+    "severity": "high",
+    "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"
+      ]
+    },
+    "migration_url": "https://ai.google.dev/gemini-api/docs/deprecations",
+    "summary": "Gemini 2.0 Flash and Flash-Lite shut down June 1, 2026 — already past, these calls now fail. Migrate to gemini-2.5-flash-lite or Gemini 3.x.",
+    "source": "https://firebase.google.com/docs/ai-logic/models"
+  },
+  {
+    "id": "google-gemini-1x-shutdown",
+    "vendor": "Google (Gemini)",
+    "title": "Gemini 1.0 / 1.5 models",
+    "severity": "high",
+    "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"
+      ]
+    },
+    "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"
+  }
+]