renovate-mcp 0.3.0 → 0.5.0

package/README.md

@@ -1,43 +1,77 @@
 # renovate-mcp
 
+[![npm](https://img.shields.io/npm/v/renovate-mcp.svg)](https://www.npmjs.com/package/renovate-mcp)
+[![CI](https://github.com/tibuntu/renovate-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/tibuntu/renovate-mcp/actions/workflows/ci.yml)
+[![Node ≥ 24](https://img.shields.io/node/v/renovate-mcp.svg)](https://nodejs.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
+
 An MCP server for designing [Renovate](https://github.com/renovatebot/renovate) configurations interactively. Point it at a local repo and let an LLM help you read, validate, preview, and save `renovate.json`.
 
+## Contents
+
+- [What it does](#what-it-does)
+- [What this is NOT](#what-this-is-not)
+- [Requirements](#requirements)
+- [Install](#install)
+- [Example prompts](#example-prompts)
+- [Example session](#example-session)
+- [Development](#development)
+- [Release flow](#release-flow)
+- [Design notes](#design-notes)
+
 ## What it does
 
-Seven tools plus a preset reference:
+Eight tools plus a preset reference:
 
-| Tool | What it does |
+| Tool | Purpose |
 | --- | --- |
-| `check_setup` | Report Renovate CLI + validator availability, versions, env overrides, and install hints. Also runs at server startup and embeds the result in the server's `instructions` when anything's missing. |
-| `read_config` | Locate and parse `renovate.json` / `renovate.json5` / `.renovaterc*` / `.github/renovate.json` / `.gitlab/renovate.json` / `package.json#renovate` in a repo — in Renovate's priority order. |
-| `resolve_config` | Expand every `extends` preset against the committed catalogue and return the fully resolved config (offline; no `renovate` invocation). Flags unresolvable entries with a reason. Opt in to fetching `github>` / `gitlab>` presets over HTTPS with `externalPresets: true` (auth via `GITHUB_TOKEN` / `GITLAB_TOKEN` / `RENOVATE_TOKEN`). For GitHub Enterprise or self-hosted GitLab, pass `endpoint` (API base URL) — and `platform` in addition to route `local>` presets through the same host. `bitbucket>`, `gitea>`, and npm presets remain in `presetsUnresolved` regardless. |
-| `preview_custom_manager` | Preview a `customManagers` (regex) entry against a local repo — offline, no `renovate` invocation. Shows which files match `fileMatch`, which lines match each `matchStrings` regex with named capture groups, and what dep info the template fields produce. Intended for fast regex iteration; run `dry_run` afterwards for full-fidelity confirmation. |
+| `check_setup` | Report Renovate CLI + validator availability, versions, and install hints. Also runs at startup. |
+| `read_config` | Locate and parse a repo's Renovate config (`renovate.json`, `renovate.json5`, `.renovaterc*`, `package.json#renovate`, …) in priority order. |
+| `resolve_config` | Expand every `extends` preset offline. Opt in to fetching `github>` / `gitlab>` presets over HTTPS with `externalPresets: true`. |
+| `preview_custom_manager` | Preview a `customManagers` (regex) entry against a local repo — shows file/line hits and extracted dep info. Offline. |
 | `validate_config` | Run `renovate-config-validator` against a file or inline object. |
-| `dry_run` | Run Renovate with `--platform=local --dry-run`, return the structured JSON report (no PRs, no pushes). |
-| `write_config` | Validate, then write a config to disk (temp-file → validate → atomic rename). Refuses to save invalid configs unless `force: true`. |
-| `renovate://presets` (resource) | Thin markdown index of every namespace (with preset counts) covering all 1000+ built-in presets. Snapshot from the installed `renovate` devDep. |
-| `renovate://presets/{namespace}` (resource template) | Markdown listing of every preset in a single namespace (e.g. `renovate://presets/config`). Fetch this instead of the full index when the LLM only cares about one namespace — cuts token cost by roughly 1/N where N is the number of namespaces. |
-| `renovate://preset/{name}` (resource template) | Expanded JSON body (description, extends, packageRules, …) for any single built-in preset. E.g. `renovate://preset/config:recommended`. |
+| `lint_config` | Semantic lint for Renovate-specific footguns schema validation misses (mostly malformed `/…/` regex patterns). Offline. |
+| `dry_run` | Run Renovate with `--platform=local --dry-run` and return the structured JSON report. No PRs, no pushes. Emits MCP progress notifications during the run when the caller supplies a `progressToken`. |
+| `write_config` | Validate, then atomically write a config to disk. Refuses to save invalid configs unless `force: true`. |
+| `renovate://presets` (resource) | Markdown index of all 1000+ built-in presets grouped by namespace. |
+| `renovate://presets/{namespace}` (resource template) | Markdown listing for a single namespace (e.g. `renovate://presets/config`) — cheaper than the full index. |
+| `renovate://preset/{name}` (resource template) | Expanded JSON body for one preset (e.g. `renovate://preset/config:recommended`). |
+
+See [Design notes](#design-notes) for implementation details (timeouts, safety caps, auth scrubbing, merge semantics).
+
+## What this is NOT
+
+- **Not a Renovate replacement.** This server doesn't open PRs, run scheduled updates, or execute in CI — it's a design-time companion for a local `renovate.json`. Use the real Renovate for the actual dependency-update pipeline.
+- **`resolve_config` is preview-quality.** Preset expansion runs against a committed snapshot, and template substitution implements only positional `{{argN}}` placeholders — non-positional tokens and Handlebars helpers are flagged in `warnings` and pass through verbatim. For authoritative output, run `dry_run`.
+- **`preview_custom_manager` is a subset of Renovate's regex manager.** It covers `customType: "regex"`, `matchStringsStrategy: "any"`, and `{{groupName}}` template substitution only — other custom types, other strategies, and full Handlebars (helpers, conditionals) are not implemented. Use it for fast regex iteration; confirm with `dry_run`.
+- **`validate_config` / `dry_run` aren't exercised in CI.** CI deliberately doesn't install Renovate, so tools that shell out to it are only covered by unit/integration tests that don't require the binary. Run them locally against the Renovate install you intend to deploy with.
 
 ## Requirements
 
+**Required**
+
 - Node.js ≥ 24 (aligns with Renovate's own engine requirement).
-- Renovate available on your `PATH` — either a global install (`npm i -g renovate`) or a project-local install that exposes `renovate` and `renovate-config-validator` via `npm exec`. Only needed for `validate_config`, `dry_run`, and `write_config`; the offline tools (`read_config`, `resolve_config`, `preview_custom_manager`) work without it.
-- Override binary locations with env vars if needed: `RENOVATE_BIN`, `RENOVATE_CONFIG_VALIDATOR_BIN`.
-- Optional for `resolve_config` with `externalPresets: true`: `GITHUB_TOKEN` / `GITLAB_TOKEN` (or `RENOVATE_TOKEN` as a fallback) for fetching presets from private repos or to avoid rate limits. For GitHub Enterprise / self-hosted GitLab, pass the `endpoint` tool input (and `platform` if you also want `local>` presets routed there); `RENOVATE_ENDPOINT` is **not** read. Any env vars the tool does read must be set on the MCP server process itself — via the `env` key in `claude_desktop_config.json` / `.mcp.json`, not your shell, since the MCP server runs as a child of Claude and does not inherit shell env.
+- Renovate on your `PATH` — either a global install (`npm i -g renovate`) or a project-local install that exposes `renovate` + `renovate-config-validator` via `npm exec`. Only needed for `validate_config`, `dry_run`, and `write_config`; the offline tools (`read_config`, `resolve_config`, `preview_custom_manager`, `lint_config`) work without it.
+
+**Optional**
+
+- `RENOVATE_BIN` / `RENOVATE_CONFIG_VALIDATOR_BIN` — override binary locations.
+- `RENOVATE_MCP_REQUIRE_CLI=false` — suppress the startup "partial availability" notice when you only intend to use the offline tools.
+- `RENOVATE_TOKEN` (preferred) or `GITHUB_TOKEN` / `GITLAB_TOKEN` as platform-specific fallbacks — only needed by `resolve_config` with `externalPresets: true` for fetching presets from private repos or avoiding rate limits. `RENOVATE_TOKEN` wins when both are set. For GitHub Enterprise / self-hosted GitLab, pass the `endpoint` tool input (and `platform` to route `local>` presets through the same host); `RENOVATE_ENDPOINT` is **not** read.
+- Private-registry credentials for `dry_run` — whatever Renovate itself would need at lookup time (`COMPOSER_AUTH`, `NPM_TOKEN` / `.npmrc`, Docker registry creds, or a `RENOVATE_HOST_RULES` JSON blob). Alternatively encode these as `hostRules` in the Renovate config, or pass them per-call via the `hostRules` input on `dry_run` (no MCP restart needed). Per-call `hostRules` are appended to whatever the repo's own config declares. Values reach Renovate as JSON through the tool-call transport, so the calling LLM sees them in its context — prefer the env route if that matters. Without any of these, Renovate's lookup often returns 0 updates silently; `dry_run` scans its logs for auth failures and surfaces them under `problems`.
+
+> **Note:** all env vars (tokens, `COMPOSER_AUTH`, `RENOVATE_HOST_RULES`, binary overrides, …) must be set on the MCP server process itself — via the `env` key in `claude_desktop_config.json` / `.mcp.json`, not your shell — since the MCP server runs as a child of the client and does not inherit shell env.
 
 ## Install
 
-Once published to npm, no install is needed — `npx` will fetch it on demand. For local development, clone and build:
+`npx` fetches the [published package](https://www.npmjs.com/package/renovate-mcp) on demand — no manual install needed. For local development, clone and build first:
 
 ```bash
 npm install
 npm run build
 ```
 
-## Use with Claude Code
-
-Add to `.mcp.json` (project) or `~/.claude.json` (user):
+Add the following `mcpServers` entry to your client's config file:
 
 ```json
 {
@@ -50,33 +84,27 @@ Add to `.mcp.json` (project) or `~/.claude.json` (user):
 }
 ```
 
-For local development, swap to:
+For local development, swap to `"command": "node"` with `"args": ["/absolute/path/to/renovate-mcp/dist/index.js"]`.
 
-```json
-{
-  "mcpServers": {
-    "renovate": {
-      "command": "node",
-      "args": ["/absolute/path/to/renovate-mcp/dist/index.js"]
-    }
-  }
-}
-```
+### Claude Code
 
-## Use with Claude Desktop
+Config lives in `.mcp.json` (project-scoped) or `~/.claude.json` (user-scoped).
 
-Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
+### Claude Desktop
 
-```json
-{
-  "mcpServers": {
-    "renovate": {
-      "command": "npx",
-      "args": ["-y", "renovate-mcp"]
-    }
-  }
-}
-```
+Config lives in `~/Library/Application Support/Claude/claude_desktop_config.json`.
+
+### Other MCP clients
+
+Any client that can launch a stdio MCP server works — point it at the same command shown above.
+
+### Verify the wiring
+
+Restart your client and prompt it:
+
+> List the namespaces available under `renovate://presets`.
+
+A response listing namespaces like `config`, `docker`, `npm`, `helpers`, … confirms the server is reachable and the resource is exposed. If the client reports the tool or resource as unavailable, re-check the config file path and command.
 
 ## Example prompts
 
@@ -111,6 +139,32 @@ Once the server is wired up, try prompts like these. They're written for Claude
 - "Do a dry run and show me which PRs Renovate would open — no pushes."
 - "Add `:semanticCommits` to my `extends`, validate it, and save back to `renovate.json`."
 
+## Example session
+
+A transcript-style walkthrough: design a Dockerfile custom manager from scratch, validate it, dry-run, and save. Turns are abbreviated — your client will show the actual tool-call JSON.
+
+> **You:** I've got `# renovate: datasource=docker depName=<image>` comments above `FROM` lines in my Dockerfiles. Draft a `customManagers` entry and preview it against this repo.
+>
+> **Claude** calls `preview_custom_manager` with a first-draft `fileMatch` + `matchStrings`.
+> → 4 Dockerfiles matched `fileMatch`, 0 lines matched `matchStrings`. The regex anchored on `ARG`, but the Dockerfiles use `FROM`.
+>
+> **You:** Rewrite `matchStrings` to anchor on the renovate comment, then `FROM <image>:<version>` on the next line.
+>
+> **Claude** calls `preview_custom_manager` again with the fixed regex.
+> → 4 files, 4 line hits. Extracted: `postgres:15.3-alpine`, `redis:7.2`, `nginx:1.25`, `node:20.11`. Named groups `depName` and `currentValue` populated on every hit.
+>
+> **You:** Good. Validate the full config inline, with this `customManagers` entry alongside my existing `extends`.
+>
+> **Claude** calls `validate_config` with the inline config. → valid.
+>
+> **You:** Now dry-run so I can see what Renovate would actually open.
+>
+> **Claude** calls `dry_run`. → 2 updates: `postgres` 15.3-alpine → 15.5-alpine, `redis` 7.2 → 7.4. No entries in `problems`.
+>
+> **You:** Save it.
+>
+> **Claude** calls `write_config` on `renovate.json`. → validated, written atomically.
+
 ## Development
 
 ```bash
@@ -120,12 +174,13 @@ npm run build            # compile to dist/
 npm start                # run the built server over stdio
 npm test                 # vitest run (builds first)
 npm run test:watch       # vitest watch mode
+npm run test:coverage    # vitest run --coverage (writes coverage/ report)
 npm run generate:presets # regenerate src/data/presets.generated.ts from the renovate devDep
 ```
 
 The preset catalogue at `src/data/presets.generated.ts` is a committed snapshot of Renovate's built-in presets. Runtime code never imports the `renovate` package — only `scripts/generate-presets.mjs` does. Regenerate after bumping the `renovate` devDependency.
 
-CI runs `typecheck`, `build`, and `test` on Node 24 for every PR and push to `main` (see `.github/workflows/ci.yml`).
+CI runs `typecheck`, `build`, and `test:coverage` on Node 24 for every PR and push to `main` (see `.github/workflows/ci.yml`). Coverage is uploaded as a per-run artifact; no threshold is enforced yet.
 
 ## Release flow
 
@@ -142,9 +197,18 @@ Secrets required on the repo: `RELEASE_PLEASE_TOKEN` (a PAT for release-please).
 
 ## Design notes
 
+Scope and non-goals are summarized in [What this is NOT](#what-this-is-not); this section covers implementation decisions behind the scope that *is* supported.
+
 - `validate_config`, `dry_run`, and `write_config` shell out to the Renovate CLI rather than importing Renovate as a library — this decouples our Node version from Renovate's (currently Node 24).
-- `resolve_config` and `preview_custom_manager` are fully in-process and never invoke the Renovate CLI, so they work without a Renovate install.
-- `preview_custom_manager` honors `.gitignore` (including nested `.gitignore`s and `.git/info/exclude`) when walking the repo, so generated/vendored directories like `dist/`, `.next/`, `target/`, `__pycache__/` don't crowd out real hits against the `maxFilesScanned` cap. `node_modules/` and `.git/` are always skipped as a safety net even when no `.gitignore` is present.
+- `resolve_config`, `preview_custom_manager`, and `lint_config` are fully in-process and never invoke the Renovate CLI, so they work without a Renovate install.
+- `lint_config` is a semantic lint pass that sits alongside `validate_config` rather than replacing it: schema validation catches structural bugs, the linter catches Renovate-specific footguns that schema validation declares valid — most commonly a pattern like `"matchPackageNames": ["/devops\\/pipelines\\/.+"]` where a trailing `/` is missing and Renovate silently degrades the value to an exact-string match that never hits. The ruleset is intentionally small (two rules: `dead-regex-missing-slash`, `unwrapped-regex`), scoped to the four regex-aware fields named in the proposal, and tuned to avoid false positives on benign exact strings containing a `.`. Rule IDs are stable so findings can be suppressed by callers.
+- `preview_custom_manager` honors `.gitignore` (including nested `.gitignore`s and `.git/info/exclude`) when walking the repo, so generated/vendored directories like `dist/`, `.next/`, `target/`, `__pycache__/` don't crowd out real hits against the `maxFilesWalked` cap. `node_modules/` and `.git/` are always skipped as a safety net even when no `.gitignore` is present.
+- `preview_custom_manager` exposes two separate safety caps so the warning text can name which one tripped: `maxFilesWalked` (default 2000) bounds the directory walk before any `fileMatch` testing, and `maxFilesMatched` (default 500) bounds the result set after `fileMatch` is applied. Previously a single `maxFilesScanned` conflated the two, leaving the user unable to tell whether to narrow `fileMatch` or widen the walk.
+- `preview_custom_manager` runs every user-supplied regex on a `worker_threads` worker with a wall-clock budget per operation (default 2 s, configurable via `matchTimeoutMs`). Catastrophic backtracking — e.g. `^(a+)+b$` against `aaaa…c`, or `(.*)*=` against a modestly sized file — would otherwise pin the MCP server's event loop indefinitely. On timeout the worker is terminated and a warning is appended identifying which `fileMatch[i]` or `matchStrings[i]` was aborted, so the user can simplify the pattern or raise the budget.
+- `preview_custom_manager` also stats each matched file before reading it and skips anything larger than `maxFileBytes` (default 5 MiB) with a warning, so a stray lockfile, generated artifact, or SQL dump caught by a loose `fileMatch` can't OOM the server. `maxHitsPerFile` already bounds output size; this guards input size.
 - `resolve_config` expands `extends` against a committed snapshot of Renovate's built-in presets (`src/data/presets.generated.ts`). External `github>` / `gitlab>` fetching is opt-in, uses each platform's contents API with a 10 s timeout, and caches results per call. The `endpoint` input swaps in a custom API base for GHE / self-hosted GitLab; `platform` additionally rewrites `local>` presets to be fetched against that endpoint.
-- `dry_run` uses `--report-type=file` so we get a structured JSON report instead of scraping stdout.
+- `resolve_config` merges preset bodies with a close approximation of Renovate's own `mergeChildConfig` — arrays concat, objects recursively merge, scalars overwrite — not a bit-identical port. Rule-specific semantics for `hostRules`, `regexManagers` / `customManagers`, and certain boolean flags aren't modeled here. Every response carries `mergeQuality: "preview"` plus a human-readable `disclaimer` so callers can't miss the limitation; run `dry_run` for authoritative output.
+- When `resolve_config` encounters template tokens outside its supported subset, it records a structured entry in `warnings`: under-argument cases (`{{arg2}}` referenced when only one arg was passed) substitute an empty string, while non-positional tokens (`{{packageRules}}`, Handlebars helpers like `{{#if …}}`) pass through verbatim.
+- `dry_run` uses `--report-type=file` so we get a structured JSON report instead of scraping stdout. When a `hostRules` input is passed it's written to a mode-0600 temp file in `os.tmpdir()`, handed to Renovate via `--config-file=`, and deleted in a `finally` block. Token/password values are scrubbed from both the detected `problems` list and the `logTail` fallback before returning.
+- `dry_run` emits MCP progress notifications only when the caller's `tools/call` includes `_meta.progressToken` — no-op otherwise, so legacy clients see zero overhead. A 5-second heartbeat ticks while the child runs; each tick's message is best-effort enriched with the latest Renovate JSON-log `msg` seen on stdout. Notifications are also emitted at start and completion. We deliberately don't couple to Renovate's log schema beyond reading `msg`, since that schema isn't a stable API.
 - `write_config` writes to a temp file, validates, then atomically renames — so a failed validation never leaves a broken config on disk.

package/dist/index.js

@@ -4,12 +4,13 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { registerCheckSetup } from "./tools/checkSetup.js";
 import { registerReadConfig } from "./tools/readConfig.js";
 import { registerValidateConfig } from "./tools/validateConfig.js";
+import { registerLintConfig } from "./tools/lintConfig.js";
 import { registerResolveConfig } from "./tools/resolveConfig.js";
 import { registerPreviewCustomManager } from "./tools/previewCustomManager.js";
 import { registerDryRun } from "./tools/dryRun.js";
 import { registerWriteConfig } from "./tools/writeConfig.js";
 import { registerPresetResources } from "./resources/presets.js";
-import { checkSetup, describeSetup } from "./lib/setupCheck.js";
+import { checkSetup, startupBanner } from "./lib/setupCheck.js";
 const BASE_INSTRUCTIONS = [
     "Design and debug Renovate configurations interactively.",
     "",
@@ -18,23 +19,28 @@ const BASE_INSTRUCTIONS = [
     "  2. resolve_config         — expand built-in presets to see what a config actually becomes (offline)",
     "  3. preview_custom_manager — iterate on a regex-based customManagers entry; shows file/line hits and extracted deps",
     "  4. validate_config        — check a proposed config against Renovate's schema",
-    "  5. dry_run                — preview what Renovate would actually do (no PRs)",
-    "  6. write_config           — save the agreed-upon config (validates first)",
+    "  5. lint_config            — semantic lint pass: catches Renovate-specific footguns schema validation misses (e.g. malformed /…/ regex patterns)",
+    "  6. dry_run                — preview what Renovate would actually do (no PRs)",
+    "  7. write_config           — save the agreed-upon config (validates first)",
     "",
     "If any tool fails unexpectedly, call check_setup to diagnose CLI availability.",
     "Built-in preset reference: renovate://presets (namespace index), renovate://presets/{namespace} (one namespace), renovate://preset/{name} (one preset's expanded JSON).",
 ].join("\n");
 const setup = await checkSetup();
-const instructions = setup.ok
-    ? BASE_INSTRUCTIONS
-    : [BASE_INSTRUCTIONS, "", "Startup setup check:", describeSetup(setup)].join("\n");
-const SERVER_VERSION = "0.3.0"; // x-release-please-version
+// `RENOVATE_MCP_REQUIRE_CLI=false` is the opt-out for users who have
+// consciously chosen the offline subset and don't want the startup notice.
+const requireCliRaw = process.env.RENOVATE_MCP_REQUIRE_CLI?.trim().toLowerCase();
+const suppressBanner = requireCliRaw === "false" || requireCliRaw === "0";
+const banner = suppressBanner ? null : startupBanner(setup);
+const instructions = banner ? [BASE_INSTRUCTIONS, "", banner].join("\n") : BASE_INSTRUCTIONS;
+const SERVER_VERSION = "0.5.0"; // x-release-please-version
 const server = new McpServer({ name: "renovate-mcp", version: SERVER_VERSION }, { instructions });
 registerCheckSetup(server);
 registerReadConfig(server);
 registerResolveConfig(server);
 registerPreviewCustomManager(server);
 registerValidateConfig(server);
+registerLintConfig(server);
 registerDryRun(server);
 registerWriteConfig(server);
 registerPresetResources(server);

package/dist/lib/configLinter.d.ts

@@ -0,0 +1,8 @@
+export type LintRuleId = "dead-regex-missing-slash" | "unwrapped-regex";
+export interface LintFinding {
+    ruleId: LintRuleId;
+    path: string;
+    value: string;
+    message: string;
+}
+export declare function lintConfig(config: unknown): LintFinding[];

package/dist/lib/configLinter.js

@@ -0,0 +1,74 @@
+const REGEX_AWARE_FIELDS = new Set([
+    "matchPackageNames",
+    "matchDepNames",
+    "matchSourceUrls",
+    "matchCurrentVersion",
+]);
+export function lintConfig(config) {
+    const findings = [];
+    walk(config, "", findings);
+    return findings;
+}
+function walk(node, pathStr, findings) {
+    if (Array.isArray(node)) {
+        node.forEach((item, i) => walk(item, `${pathStr}[${i}]`, findings));
+        return;
+    }
+    if (node && typeof node === "object") {
+        for (const [key, value] of Object.entries(node)) {
+            const childPath = pathStr ? `${pathStr}.${key}` : key;
+            if (REGEX_AWARE_FIELDS.has(key)) {
+                if (Array.isArray(value)) {
+                    value.forEach((entry, i) => {
+                        if (typeof entry === "string") {
+                            checkPattern(entry, `${childPath}[${i}]`, findings);
+                        }
+                    });
+                }
+                else if (typeof value === "string") {
+                    checkPattern(value, childPath, findings);
+                }
+            }
+            else {
+                walk(value, childPath, findings);
+            }
+        }
+    }
+}
+function checkPattern(raw, path, findings) {
+    // `!` is Renovate's exclusion prefix; strip it before checking regex wrapping.
+    const stripped = raw.startsWith("!") ? raw.slice(1) : raw;
+    // Too short to meaningfully be a /…/ regex or trigger a metachar rule.
+    if (stripped.length < 2)
+        return;
+    const startsSlash = stripped.startsWith("/");
+    const endsSlash = stripped.endsWith("/");
+    if (startsSlash !== endsSlash) {
+        findings.push({
+            ruleId: "dead-regex-missing-slash",
+            path,
+            value: raw,
+            message: startsSlash
+                ? "Value starts with '/' but does not end with '/'. Renovate will treat this as an exact-match string, not a regex. Add the trailing '/' if a regex match was intended, otherwise remove the leading '/'."
+                : "Value ends with '/' but does not start with '/'. Renovate will treat this as an exact-match string, not a regex. Add the leading '/' if a regex match was intended, otherwise remove the trailing '/'.",
+        });
+        return;
+    }
+    if (startsSlash && endsSlash)
+        return;
+    if (hasStrongRegexSignal(stripped)) {
+        findings.push({
+            ruleId: "unwrapped-regex",
+            path,
+            value: raw,
+            message: `Value contains regex metacharacters but is not wrapped in '/…/'. Renovate will treat it as an exact-match string. Wrap it as '/${stripped}/' (or '!/${stripped}/' to negate) if a regex match was intended.`,
+        });
+    }
+}
+function hasStrongRegexSignal(s) {
+    return (/\\[dwsbDWSB]/.test(s) ||
+        /\.[+*?]/.test(s) ||
+        /\\\./.test(s) ||
+        /\(\?[:!=<]/.test(s) ||
+        /\[[^\]]+\]/.test(s));
+}

package/dist/lib/customManagerPreview.d.ts

@@ -36,11 +36,14 @@ export interface ExtractedDep {
     autoReplaceString?: string;
 }
 export interface PreviewOptions {
-    maxFilesScanned?: number;
+    maxFilesWalked?: number;
+    maxFilesMatched?: number;
     maxHitsPerFile?: number;
+    matchTimeoutMs?: number;
+    maxFileBytes?: number;
 }
 export interface PreviewResult {
-    filesScanned: number;
+    filesWalked: number;
     filesMatched: string[];
     hits: PreviewHit[];
     extractedDeps: ExtractedDep[];

package/dist/lib/customManagerPreview.js

@@ -1,8 +1,12 @@
 import { promises as fs } from "node:fs";
 import path from "node:path";
+import { Worker } from "node:worker_threads";
 import ignore from "ignore";
-const DEFAULT_MAX_FILES_SCANNED = 2000;
+const DEFAULT_MAX_FILES_WALKED = 2000;
+const DEFAULT_MAX_FILES_MATCHED = 500;
 const DEFAULT_MAX_HITS_PER_FILE = 100;
+const DEFAULT_MATCH_TIMEOUT_MS = 2000;
+const DEFAULT_MAX_FILE_BYTES = 5 * 1024 * 1024;
 const SKIP_DIRS = new Set([".git", "node_modules"]);
 const TEMPLATE_FIELD_MAP = [
     ["depNameTemplate", "depName"],
@@ -18,29 +22,67 @@ const TEMPLATE_FIELD_MAP = [
 ];
 export async function previewCustomManager(repoPath, manager, options = {}) {
     const warnings = [];
-    const maxFilesScanned = options.maxFilesScanned ?? DEFAULT_MAX_FILES_SCANNED;
+    const maxFilesWalked = options.maxFilesWalked ?? DEFAULT_MAX_FILES_WALKED;
+    const maxFilesMatched = options.maxFilesMatched ?? DEFAULT_MAX_FILES_MATCHED;
     const maxHitsPerFile = options.maxHitsPerFile ?? DEFAULT_MAX_HITS_PER_FILE;
+    const matchTimeoutMs = options.matchTimeoutMs ?? DEFAULT_MATCH_TIMEOUT_MS;
+    const maxFileBytes = options.maxFileBytes ?? DEFAULT_MAX_FILE_BYTES;
     if (manager.matchStringsStrategy && manager.matchStringsStrategy !== "any") {
         warnings.push(`matchStringsStrategy='${manager.matchStringsStrategy}' is not yet supported by this preview tool; treating as 'any'. Run dry_run for full-fidelity behavior.`);
     }
-    const fileMatchRes = manager.fileMatch.map((s) => compileRegex(s));
-    const matchStringRes = manager.matchStrings.map((s) => compileRegex(s, "gm"));
-    const filesMatched = [];
-    let filesScanned = 0;
+    // Surface malformed user regexes eagerly, before we do any filesystem work.
+    // The Worker path otherwise reports these as generic worker errors.
+    for (const src of manager.fileMatch)
+        validateRegex(src);
+    for (const src of manager.matchStrings)
+        validateRegex(src);
+    // Walk first, then run fileMatch regexes in a worker so a pathological
+    // pattern can't pin the event loop on the path-testing phase.
+    const allPaths = [];
     for await (const rel of walk(repoPath)) {
-        if (filesScanned >= maxFilesScanned) {
-            warnings.push(`Stopped after scanning ${maxFilesScanned} files. Increase maxFilesScanned to widen the search.`);
+        if (allPaths.length >= maxFilesWalked) {
+            warnings.push(`Stopped walking the repo after ${maxFilesWalked} files; remaining files were never tested against fileMatch. Add ignores (or a .gitignore) to prune irrelevant directories, or raise maxFilesWalked.`);
             break;
         }
-        filesScanned++;
-        if (fileMatchRes.some((re) => re.test(rel))) {
-            filesMatched.push(rel);
+        allPaths.push(rel);
+    }
+    const filesWalked = allPaths.length;
+    const matchedSet = new Set();
+    for (let i = 0; i < manager.fileMatch.length; i++) {
+        const source = manager.fileMatch[i];
+        const res = await runTestInWorker(source, "", allPaths, matchTimeoutMs);
+        if (res.timedOut) {
+            warnings.push(`fileMatch[${i}] /${source}/ exceeded ${matchTimeoutMs}ms and was aborted; no paths were matched against this pattern. Simplify the regex (e.g. avoid nested quantifiers like (a+)+) or raise matchTimeoutMs.`);
+            continue;
         }
+        for (const p of res.paths)
+            matchedSet.add(p);
+    }
+    // Preserve walk order so output is stable.
+    const allFilesMatched = allPaths.filter((p) => matchedSet.has(p));
+    // Distinct from the walk cap: this caps the *result set*. A broad fileMatch
+    // regex over a large repo can produce thousands of hits; truncate with a
+    // dedicated warning so the user can tell which cap tripped.
+    const filesMatched = allFilesMatched.slice(0, maxFilesMatched);
+    if (allFilesMatched.length > maxFilesMatched) {
+        warnings.push(`fileMatch matched ${allFilesMatched.length} files; capped result set at maxFilesMatched=${maxFilesMatched}. Narrow fileMatch to target the intended paths, or raise maxFilesMatched.`);
     }
     const hits = [];
     const extractedDeps = [];
     for (const rel of filesMatched) {
         const abs = path.join(repoPath, rel);
+        let stat;
+        try {
+            stat = await fs.stat(abs);
+        }
+        catch (err) {
+            warnings.push(`Could not stat ${rel}: ${err.message}`);
+            continue;
+        }
+        if (stat.size > maxFileBytes) {
+            warnings.push(`${rel}: skipped, ${stat.size} bytes exceeds maxFileBytes=${maxFileBytes}. Tighten fileMatch to exclude it, or raise maxFileBytes.`);
+            continue;
+        }
         let content;
         try {
             content = await fs.readFile(abs, "utf8");
@@ -50,28 +92,34 @@ export async function previewCustomManager(repoPath, manager, options = {}) {
             continue;
         }
         let perFileHits = 0;
-        for (let i = 0; i < matchStringRes.length; i++) {
-            const re = matchStringRes[i];
-            // RegExp objects with the `g` flag are stateful — reset before iterating
-            // each file so that previous calls don't shift lastIndex.
-            re.lastIndex = 0;
-            for (const m of content.matchAll(re)) {
+        for (let i = 0; i < manager.matchStrings.length; i++) {
+            const source = manager.matchStrings[i];
+            const res = await runMatchAllInWorker(source, "gm", content, matchTimeoutMs);
+            if (res.timedOut) {
+                warnings.push(`${rel}: matchStrings[${i}] /${source}/ exceeded ${matchTimeoutMs}ms and was aborted; any matches in this file for this pattern were skipped. Simplify the regex (e.g. avoid nested quantifiers like (.*)*) or raise matchTimeoutMs.`);
+                continue;
+            }
+            for (const m of res.matches) {
                 if (perFileHits >= maxHitsPerFile) {
                     warnings.push(`${rel}: capped at ${maxHitsPerFile} hits. Increase maxHitsPerFile to see more.`);
                     break;
                 }
-                const groups = (m.groups ?? {});
-                const line = lineNumberAt(content, m.index ?? 0);
-                const matchStr = m[0];
-                hits.push({ file: rel, matchStringIndex: i, line, match: matchStr, groups });
-                extractedDeps.push(buildExtractedDep(rel, line, groups, manager));
+                const line = lineNumberAt(content, m.index);
+                hits.push({
+                    file: rel,
+                    matchStringIndex: i,
+                    line,
+                    match: m.match,
+                    groups: m.groups,
+                });
+                extractedDeps.push(buildExtractedDep(rel, line, m.groups, manager));
                 perFileHits++;
             }
             if (perFileHits >= maxHitsPerFile)
                 break;
         }
     }
-    return { filesScanned, filesMatched, hits, extractedDeps, warnings };
+    return { filesWalked, filesMatched, hits, extractedDeps, warnings };
 }
 function buildExtractedDep(file, line, groups, manager) {
     const dep = { file, line };
@@ -102,17 +150,9 @@ function buildExtractedDep(file, line, groups, manager) {
 function applyTemplate(tmpl, groups) {
     return tmpl.replace(/\{\{\s*([a-zA-Z_$][a-zA-Z0-9_$]*)\s*\}\}/g, (_, name) => groups[name] ?? "");
 }
-function compileRegex(source, extraFlags = "") {
+function validateRegex(source) {
     try {
-        // De-duplicate flags in case the source already had `g`/`m`.
-        const seen = new Set();
-        const flags = (extraFlags).split("").filter((c) => {
-            if (seen.has(c))
-                return false;
-            seen.add(c);
-            return true;
-        }).join("");
-        return new RegExp(source, flags);
+        new RegExp(source);
     }
     catch (err) {
         throw new Error(`Invalid regex /${source}/: ${err.message}`);
@@ -126,6 +166,82 @@ function lineNumberAt(content, index) {
     }
     return line;
 }
+const WORKER_SOURCE = `
+const { parentPort, workerData } = require('node:worker_threads');
+try {
+  const { mode, pattern, flags } = workerData;
+  const re = new RegExp(pattern, flags);
+  if (mode === 'test') {
+    const out = [];
+    for (const p of workerData.paths) {
+      re.lastIndex = 0;
+      if (re.test(p)) out.push(p);
+    }
+    parentPort.postMessage({ ok: true, mode: 'test', paths: out });
+  } else {
+    const out = [];
+    for (const m of workerData.content.matchAll(re)) {
+      out.push({
+        index: m.index == null ? 0 : m.index,
+        match: m[0],
+        groups: m.groups == null ? {} : Object.assign({}, m.groups),
+      });
+    }
+    parentPort.postMessage({ ok: true, mode: 'matchAll', matches: out });
+  }
+} catch (err) {
+  parentPort.postMessage({ ok: false, error: err && err.message ? err.message : String(err) });
+}
+`;
+async function runWorker(request, timeoutMs) {
+    const worker = new Worker(WORKER_SOURCE, {
+        eval: true,
+        workerData: request,
+    });
+    let timer;
+    try {
+        return await new Promise((resolve, reject) => {
+            timer = setTimeout(() => resolve("timeout"), timeoutMs);
+            worker.once("message", (msg) => resolve(msg));
+            worker.once("error", (err) => reject(err));
+            worker.once("exit", (code) => {
+                if (code !== 0 && code !== 1) {
+                    // code 1 is the normal exit after terminate(); anything else is a
+                    // crash we haven't already captured via 'error'.
+                    reject(new Error(`Regex worker exited unexpectedly with code ${code}`));
+                }
+            });
+        });
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+        // terminate() is idempotent and safe to call after the worker already exited.
+        await worker.terminate().catch(() => { });
+    }
+}
+async function runTestInWorker(pattern, flags, paths, timeoutMs) {
+    const response = await runWorker({ mode: "test", pattern, flags, paths }, timeoutMs);
+    if (response === "timeout")
+        return { timedOut: true };
+    if (!response.ok)
+        throw new Error(`Regex worker error: ${response.error}`);
+    if (response.mode !== "test") {
+        throw new Error(`Regex worker returned wrong mode: ${response.mode}`);
+    }
+    return { timedOut: false, paths: response.paths };
+}
+async function runMatchAllInWorker(pattern, flags, content, timeoutMs) {
+    const response = await runWorker({ mode: "matchAll", pattern, flags, content }, timeoutMs);
+    if (response === "timeout")
+        return { timedOut: true };
+    if (!response.ok)
+        throw new Error(`Regex worker error: ${response.error}`);
+    if (response.mode !== "matchAll") {
+        throw new Error(`Regex worker returned wrong mode: ${response.mode}`);
+    }
+    return { timedOut: false, matches: response.matches };
+}
 async function readMaybe(abs) {
     try {
         return await fs.readFile(abs, "utf8");