renovate-mcp 1.2.0 → 1.3.0

package/README.md

@@ -39,7 +39,7 @@ Restart your client and try the prompt: *"List the namespaces available under `r
 
 ## Tools & resources
 
-Fourteen tools and three resource templates. Each tool name below links to its full reference in [`docs/tools.md`](docs/tools.md).
+Sixteen tools and three resource templates. Each tool name below links to its full reference in [`docs/tools.md`](docs/tools.md).
 
 | Tool | Purpose |
 | --- | --- |
@@ -50,11 +50,13 @@ Fourteen tools and three resource templates. Each tool name below links to its f
 | [`resolve_config`](docs/tools.md#resolve_config) | Expand every `extends` preset offline. Opt in to fetching `github>` / `gitlab>` presets over HTTPS. |
 | [`explain_config`](docs/tools.md#explain_config) | Inverse of `resolve_config`: annotate every leaf field with the chain of presets that set it. |
 | [`resolve_config_diff`](docs/tools.md#resolve_config_diff) | Offline structural diff of two fully-resolved configs — changed fields plus an order-insensitive set diff of array keys (`packageRules`, `customManagers`, …). The refactor-friendly counterpart to `dry_run_diff`. |
+| [`test_package_rules`](docs/tools.md#test_package_rules) | Offline what-if: which `packageRules` match a hypothetical dependency, which matcher decided each, and what each contributes. Faithful (Renovate's real matchers in a worker); fields you don't supply are reported as unevaluatable, not non-matches. |
 | [`preview_custom_manager`](docs/tools.md#preview_custom_manager) | Preview a `customManagers` entry (regex or JSONata) against a local repo. Offline. |
 | [`validate_config`](docs/tools.md#validate_config) | Run `renovate-config-validator` against a file or inline object. |
 | [`lint_config`](docs/tools.md#lint_config) | Semantic lint pass for Renovate-specific footguns the schema validator declares valid. Offline. |
 | [`dry_run`](docs/tools.md#dry_run) | Run Renovate with `--dry-run` and return the structured JSON report. Local-by-default; remote with `platform` + `endpoint` + `token` + `repository`. No PRs, no pushes. |
 | [`dry_run_diff`](docs/tools.md#dry_run_diff) | Stateless semantic diff between two `dry_run` reports — added / removed / changed updates. |
+| [`annotate_dry_run`](docs/tools.md#annotate_dry_run) | Attribute each proposed update in a `dry_run` report to the `packageRules` that caused it; flags rules that never matched and report fields the matchers needed but the report lacked. Stateless + offline. |
 | [`migrate_config`](docs/tools.md#migrate_config) | Apply Renovate's built-in migrations and return the migrated config plus a unified diff. Does not write. |
 | [`write_config`](docs/tools.md#write_config) | Validate, then atomically write a config to disk. Preserves comments/key order on existing JSON-with-comments files. |
 | [`renovate://presets`](docs/tools.md#renovatepresets) (resource) | Markdown index of all built-in presets grouped by namespace. |

package/dist/data/managers.generated.d.ts

@@ -1,4 +1,4 @@
-export declare const RENOVATE_VERSION = "43.233.4";
+export declare const RENOVATE_VERSION = "43.245.0";
 /**
  * All manager names accepted by Renovate's `matchManagers` /
  * `excludeManagers` fields. Includes both regular managers and custom

package/dist/data/managers.generated.js

@@ -1,6 +1,6 @@
-// AUTO-GENERATED by scripts/generate-managers.mjs from renovate@43.233.4.
+// AUTO-GENERATED by scripts/generate-managers.mjs from renovate@43.245.0.
 // Do not edit by hand. Run `npm run generate:managers` to refresh.
-export const RENOVATE_VERSION = "43.233.4";
+export const RENOVATE_VERSION = "43.245.0";
 /**
  * All manager names accepted by Renovate's `matchManagers` /
  * `excludeManagers` fields. Includes both regular managers and custom

package/dist/data/migrations.generated.d.ts

@@ -1,4 +1,4 @@
-export declare const RENOVATE_VERSION = "43.233.4";
+export declare const RENOVATE_VERSION = "43.245.0";
 export interface DeprecatedKeyEntry {
     /** Key as it appeared in old configs. */
     readonly oldKey: string;

package/dist/data/migrations.generated.js

@@ -1,6 +1,6 @@
-// AUTO-GENERATED by scripts/generate-migrations.mjs from renovate@43.233.4.
+// AUTO-GENERATED by scripts/generate-migrations.mjs from renovate@43.245.0.
 // Do not edit by hand. Run `npm run generate:migrations` to refresh.
-export const RENOVATE_VERSION = "43.233.4";
+export const RENOVATE_VERSION = "43.245.0";
 /**
  * Deprecated config keys with their current replacement. Sourced from
  * Renovate's `MigrationsService.renamedProperties` — the "RenamePropertyMigration"

package/dist/data/presets.generated.d.ts

@@ -3,6 +3,6 @@ export interface GeneratedPreset {
     description: string | null;
     body: Record<string, unknown>;
 }
-export declare const RENOVATE_VERSION = "43.233.4";
+export declare const RENOVATE_VERSION = "43.245.0";
 export declare const PRESETS: Record<string, GeneratedPreset>;
 export declare const PRESET_NAMES: readonly string[];

package/dist/data/presets.generated.js

@@ -1,6 +1,6 @@
-// AUTO-GENERATED by scripts/generate-presets.mjs from renovate@43.233.4.
+// AUTO-GENERATED by scripts/generate-presets.mjs from renovate@43.245.0.
 // Do not edit by hand. Run `npm run generate:presets` to refresh.
-export const RENOVATE_VERSION = "43.233.4";
+export const RENOVATE_VERSION = "43.245.0";
 export const PRESETS = {
     "abandonments:recommended": {
         "namespace": "abandonments",
@@ -17861,6 +17861,7 @@ export const PRESETS = {
                 "replacements:actions-attest-build-provenance-to-actions-attest",
                 "replacements:airbnb-prop-types-to-prop-types-tools",
                 "replacements:apollo-server-to-scoped",
+                "replacements:aws-sdk-smithy-client-to-smithy",
                 "replacements:babel-eslint-to-eslint-parser",
                 "replacements:base-ui-components-to-base-ui",
                 "replacements:containerbase",
@@ -18011,6 +18012,24 @@ export const PRESETS = {
             ]
         }
     },
+    "replacements:aws-sdk-smithy-client-to-smithy": {
+        "namespace": "replacements",
+        "description": "`@aws-sdk/smithy-client` was moved to `@smithy/smithy-client`.",
+        "body": {
+            "packageRules": [
+                {
+                    "matchDatasources": [
+                        "npm"
+                    ],
+                    "matchPackageNames": [
+                        "@aws-sdk/smithy-client"
+                    ],
+                    "replacementName": "@smithy/smithy-client",
+                    "replacementVersion": "1.0.5"
+                }
+            ]
+        }
+    },
     "replacements:babel-eslint-to-eslint-parser": {
         "namespace": "replacements",
         "description": "`babel-eslint` was renamed under the `@babel` scope.",

package/dist/index.js

@@ -12,6 +12,8 @@ import { registerSuggestPresets } from "./tools/suggestPresets.js";
 import { registerPreviewCustomManager } from "./tools/previewCustomManager.js";
 import { registerDryRun } from "./tools/dryRun.js";
 import { registerDryRunDiff } from "./tools/dryRunDiff.js";
+import { registerTestPackageRules } from "./tools/testPackageRules.js";
+import { registerAnnotateDryRun } from "./tools/annotateDryRun.js";
 import { registerWriteConfig } from "./tools/writeConfig.js";
 import { registerMigrateConfig } from "./tools/migrateConfig.js";
 import { registerGetVersion } from "./tools/getVersion.js";
@@ -37,13 +39,15 @@ const BASE_INSTRUCTIONS = [
     "  3. resolve_config         — expand built-in presets to see what a config actually becomes (offline)",
     "  4. explain_config         — inverse of resolve_config: trace which preset set each field (offline)",
     "  5. resolve_config_diff    — offline structural diff of two resolved configs (changed fields + array/packageRules set diffs); use this over dry_run_diff for config refactors, especially when registries are unreachable",
-    "  6. preview_custom_manager — iterate on a regex-based customManagers entry; shows file/line hits and extracted deps",
-    "  7. validate_config        — check a proposed config against Renovate's schema",
-    "  8. lint_config            — semantic lint pass: catches Renovate-specific footguns schema validation misses (e.g. malformed /…/ regex patterns)",
-    "  9. dry_run                — preview what Renovate would actually do (no PRs)",
-    " 10. dry_run_diff           — semantic diff between two dry_run reports (added/removed/changed updates)",
-    " 11. migrate_config         — apply Renovate's built-in migrations (deprecated keys → current schema) and return the migrated config",
-    " 12. write_config           — save the agreed-upon config (validates first)",
+    "  6. test_package_rules     — offline what-if: which packageRules match a hypothetical dependency, which matcher decided each, and what each contributes (debug \"why didn't my rule match?\")",
+    "  7. preview_custom_manager — iterate on a regex-based customManagers entry; shows file/line hits and extracted deps",
+    "  8. validate_config        — check a proposed config against Renovate's schema",
+    "  9. lint_config            — semantic lint pass: catches Renovate-specific footguns schema validation misses (e.g. malformed /…/ regex patterns)",
+    " 10. dry_run                — preview what Renovate would actually do (no PRs)",
+    " 11. dry_run_diff           — semantic diff between two dry_run reports (added/removed/changed updates)",
+    " 12. annotate_dry_run       — attribute each proposed update in a dry_run report to the packageRules that caused it (and flag rules that never matched)",
+    " 13. migrate_config         — apply Renovate's built-in migrations (deprecated keys → current schema) and return the migrated config",
+    " 14. write_config           — save the agreed-upon config (validates first)",
     "",
     "Before the first repo-touching tool call in a session (read_config, resolve_config, dry_run, write_config, …), call check_setup with the same repoPath. It surfaces token / endpoint / connectivity problems up front (e.g. \"set GITHUB_TOKEN or github-actions deps will be skipped\") instead of waiting for dry_run to fail. Skip if the user has already confirmed setup or is doing offline-only work that doesn't depend on git origin or registries.",
     "If any tool fails unexpectedly, call check_setup to diagnose CLI availability.",
@@ -72,6 +76,8 @@ registerValidateConfig(server);
 registerLintConfig(server);
 registerDryRun(server);
 registerDryRunDiff(server);
+registerTestPackageRules(server);
+registerAnnotateDryRun(server);
 registerMigrateConfig(server);
 registerWriteConfig(server);
 registerGetVersion(server);

package/dist/lib/dryRunDiff.d.ts

@@ -61,5 +61,10 @@ export interface DryRunDiff {
  * would actually become a PR — which is what the diff is about.
  */
 export declare function collectProposedUpdates(report: unknown): ProposedUpdate[];
+export declare function identityKey(u: {
+    manager: string;
+    packageFile: string;
+    depName: string;
+}): string;
 export declare function diffDryRunReports(beforeInput: unknown, afterInput: unknown): DryRunDiff;
 export {};

package/dist/lib/packageRulesAnalysis.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Shared analysis layer for `test_package_rules` and `annotate_dry_run`. Wraps
+ * the worker-isolated faithful matcher (see ADR-0006) and turns its raw
+ * per-matcher verdict vector into a human-meaningful classification:
+ *   - matched              — the matcher returned true
+ *   - real non-match       — the matcher returned false AND the caller supplied
+ *                            the field(s) it reads (so the verdict is trustworthy)
+ *   - unevaluatable        — the matcher returned false but a field it needs was
+ *                            not supplied, OR it threw (matchConfidence needs the
+ *                            merge-confidence API), OR it is a JSONata expression
+ *                            whose result may depend on unsupplied computed fields
+ *
+ * The crucial subtlety (verified in Renovate's matchers): a matcher returns
+ * `false` identically for "supplied-but-no-match" and "field-absent". Only this
+ * layer — which knows what the caller actually supplied — can tell them apart.
+ *
+ * If the worker is unavailable, falls back to a thin in-process glob-only matcher
+ * over the common static keys and reports `matchQuality: "preview"`, mirroring
+ * resolve_config / explain_config.
+ */
+export type MatchQuality = "faithful" | "preview";
+type MatcherKind = "static" | "computed" | "mc-api" | "jsonata";
+interface MatcherMeta {
+    /** Friendly `match*` key as written in a packageRule. */
+    key: string;
+    /** Context fields the matcher reads; evaluatable iff ≥1 is supplied. */
+    requiredAnyOf: string[];
+    kind: MatcherKind;
+}
+/**
+ * Class-name → metadata for every matcher in Renovate's registry. The keys are
+ * tied to the matcher-registry drift sentinel (see packageRulesWorker.test.ts):
+ * a Renovate bump that renames/adds/removes a matcher breaks both this map's
+ * coverage assertion and the sentinel, forcing a deliberate update with ADR-0006.
+ */
+export declare const MATCHER_META: Record<string, MatcherMeta>;
+export type UnevaluatableReason = "missing-input-field" | "needs-merge-confidence-api" | "jsonata-may-reference-computed-fields" | "matcher-error";
+export interface MatcherFinding {
+    /** Friendly `match*` key. */
+    matcher: string;
+    /** Context fields the matcher reads (when relevant). */
+    requiredFields: string[];
+    reason: UnevaluatableReason;
+    /** Present for matcher-error / needs-merge-confidence-api. */
+    error?: string;
+}
+export interface RuleAnalysis {
+    index: number;
+    rule: Record<string, unknown>;
+    /** True iff the rule cleanly matched (no matcher returned false, none threw). */
+    matched: boolean;
+    /** Friendly keys that returned true. */
+    matchedBy: string[];
+    /** Friendly keys that returned a trustworthy false (their fields were supplied). */
+    decidedBy: string[];
+    /** Matchers we could not evaluate (missing field, mc-api, jsonata advisory, error). */
+    unevaluatable: MatcherFinding[];
+    /** The rule's contribution (match/exclude stripped, overrides applied). Present only when matched. */
+    contributedConfig?: Record<string, unknown>;
+}
+export interface ContextAnalysis {
+    /** Faithful merged config (worker path) or approximate (preview path). */
+    mergedConfig: Record<string, unknown>;
+    rules: RuleAnalysis[];
+}
+export interface PackageRulesAnalysis {
+    matchQuality: MatchQuality;
+    contexts: ContextAnalysis[];
+    warnings: string[];
+}
+/** Field names the caller actually supplied (present and not undefined). */
+export declare function suppliedFieldsOf(context: Record<string, unknown>): Set<string>;
+/**
+ * Detect deprecated matcher keys. Renovate migrates these to matchPackageNames /
+ * matchFileNames internally before applying rules; the real matchers we evaluate
+ * only understand the migrated keys, so a legacy rule would faithfully match
+ * nothing. We warn and point at migrate_config (consistent with
+ * lint_config → migrate_config) rather than auto-migrating.
+ */
+export declare function detectLegacyKeys(packageRules: Record<string, unknown>[]): string[];
+/**
+ * Evaluate `packageRules` against each context and classify the results. The
+ * caller passes the same `contexts` it would hand the worker; `suppliedFieldsOf`
+ * is applied per context so false-vs-missing-field can be distinguished.
+ */
+export declare function analyzePackageRules(packageRules: Record<string, unknown>[], contexts: Record<string, unknown>[], options?: {
+    timeoutMs?: number;
+}): Promise<PackageRulesAnalysis>;
+export {};

package/dist/lib/packageRulesAnalysis.js

@@ -0,0 +1,252 @@
+import { runApplyPackageRules, } from "./packageRulesWorker.js";
+/**
+ * Class-name → metadata for every matcher in Renovate's registry. The keys are
+ * tied to the matcher-registry drift sentinel (see packageRulesWorker.test.ts):
+ * a Renovate bump that renames/adds/removes a matcher breaks both this map's
+ * coverage assertion and the sentinel, forcing a deliberate update with ADR-0006.
+ */
+export const MATCHER_META = {
+    MergeConfidenceMatcher: { key: "matchConfidence", requiredAnyOf: ["mergeConfidenceLevel"], kind: "mc-api" },
+    RepositoriesMatcher: { key: "matchRepositories", requiredAnyOf: ["repository"], kind: "static" },
+    BaseBranchesMatcher: { key: "matchBaseBranches", requiredAnyOf: ["baseBranch"], kind: "static" },
+    CategoriesMatcher: { key: "matchCategories", requiredAnyOf: ["categories"], kind: "static" },
+    ManagersMatcher: { key: "matchManagers", requiredAnyOf: ["manager"], kind: "static" },
+    FileNamesMatcher: { key: "matchFileNames", requiredAnyOf: ["packageFile", "lockFiles"], kind: "static" },
+    DatasourcesMatcher: { key: "matchDatasources", requiredAnyOf: ["datasource"], kind: "static" },
+    PackageNameMatcher: { key: "matchPackageNames", requiredAnyOf: ["packageName", "depName"], kind: "static" },
+    DepNameMatcher: { key: "matchDepNames", requiredAnyOf: ["depName"], kind: "static" },
+    DepTypesMatcher: { key: "matchDepTypes", requiredAnyOf: ["depType", "depTypes"], kind: "static" },
+    CurrentValueMatcher: { key: "matchCurrentValue", requiredAnyOf: ["currentValue"], kind: "static" },
+    CurrentVersionMatcher: { key: "matchCurrentVersion", requiredAnyOf: ["currentVersion", "lockedVersion"], kind: "computed" },
+    UpdateTypesMatcher: { key: "matchUpdateTypes", requiredAnyOf: ["updateType", "isBump"], kind: "computed" },
+    SourceUrlsMatcher: { key: "matchSourceUrls", requiredAnyOf: ["sourceUrl"], kind: "static" },
+    RegistryUrlsMatcher: { key: "matchRegistryUrls", requiredAnyOf: ["registryUrls"], kind: "static" },
+    NewValueMatcher: { key: "matchNewValue", requiredAnyOf: ["newValue"], kind: "computed" },
+    CurrentAgeMatcher: { key: "matchCurrentAge", requiredAnyOf: ["currentVersionTimestamp"], kind: "computed" },
+    JsonataMatcher: { key: "matchJsonata", requiredAnyOf: [], kind: "jsonata" },
+};
+const LEGACY_MATCHER_KEYS = [
+    "matchPackagePatterns",
+    "matchPackagePrefixes",
+    "excludePackagePatterns",
+    "excludePackagePrefixes",
+    "matchPaths",
+    "paths",
+];
+/** Field names the caller actually supplied (present and not undefined). */
+export function suppliedFieldsOf(context) {
+    const set = new Set();
+    for (const [k, v] of Object.entries(context)) {
+        if (v !== undefined)
+            set.add(k);
+    }
+    return set;
+}
+/**
+ * Detect deprecated matcher keys. Renovate migrates these to matchPackageNames /
+ * matchFileNames internally before applying rules; the real matchers we evaluate
+ * only understand the migrated keys, so a legacy rule would faithfully match
+ * nothing. We warn and point at migrate_config (consistent with
+ * lint_config → migrate_config) rather than auto-migrating.
+ */
+export function detectLegacyKeys(packageRules) {
+    const found = new Set();
+    for (const rule of packageRules) {
+        for (const key of LEGACY_MATCHER_KEYS) {
+            if (key in rule)
+                found.add(key);
+        }
+    }
+    if (found.size === 0)
+        return [];
+    return [
+        `Config uses deprecated matcher key(s) ${[...found]
+            .map((k) => `\`${k}\``)
+            .join(", ")}. Renovate migrates these before applying rules, but this tool ` +
+            `evaluates the real (post-migration) matchers, so those rules will appear to ` +
+            `match nothing. Run migrate_config first, then re-run this tool.`,
+    ];
+}
+/**
+ * Evaluate `packageRules` against each context and classify the results. The
+ * caller passes the same `contexts` it would hand the worker; `suppliedFieldsOf`
+ * is applied per context so false-vs-missing-field can be distinguished.
+ */
+export async function analyzePackageRules(packageRules, contexts, options = {}) {
+    const warnings = detectLegacyKeys(packageRules);
+    let workerResults;
+    try {
+        workerResults = await runApplyPackageRules(packageRules, contexts, options);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        warnings.push(`Faithful packageRules worker unavailable (${message}); used an approximate ` +
+            `glob-only preview that only evaluates matchPackageNames / matchDepNames / ` +
+            `matchManagers / matchDatasources / matchFileNames / matchCategories. Run ` +
+            `dry_run for authoritative output.`);
+        return {
+            matchQuality: "preview",
+            warnings,
+            contexts: contexts.map((ctx) => previewContext(packageRules, ctx)),
+        };
+    }
+    const analysed = workerResults.map((res, i) => {
+        const supplied = suppliedFieldsOf(contexts[i] ?? {});
+        return {
+            mergedConfig: res.mergedConfig,
+            rules: res.rules.map((ruleResult, index) => classifyRule(ruleResult, packageRules[index] ?? {}, index, supplied)),
+        };
+    });
+    return { matchQuality: "faithful", warnings, contexts: analysed };
+}
+function classifyRule(ruleResult, rule, index, supplied) {
+    const matchedBy = [];
+    const decidedBy = [];
+    const unevaluatable = [];
+    for (const m of ruleResult.matchers) {
+        const meta = MATCHER_META[m.name];
+        const key = meta?.key ?? m.name;
+        const requiredFields = meta?.requiredAnyOf ?? [];
+        if (m.result === "null")
+            continue; // matcher not used by this rule
+        if (m.result === "threw") {
+            unevaluatable.push({
+                matcher: key,
+                requiredFields,
+                reason: meta?.kind === "mc-api" ? "needs-merge-confidence-api" : "matcher-error",
+                ...(m.error ? { error: m.error } : {}),
+            });
+            continue;
+        }
+        if (meta?.kind === "jsonata") {
+            // JSONata can read any field; its verdict may depend on unsupplied
+            // computed context. Surface as advisory regardless of true/false.
+            unevaluatable.push({
+                matcher: key,
+                requiredFields: [],
+                reason: "jsonata-may-reference-computed-fields",
+            });
+            if (m.result === "true")
+                matchedBy.push(key);
+            continue;
+        }
+        if (m.result === "true") {
+            matchedBy.push(key);
+            continue;
+        }
+        // result === "false": trustworthy only if a field it reads was supplied.
+        const evaluatable = requiredFields.some((f) => supplied.has(f));
+        if (evaluatable) {
+            decidedBy.push(key);
+        }
+        else {
+            // The only way to reach here is a missing input field. mc-api matchers
+            // (matchConfidence) reach `unevaluatable` via the "threw" branch above —
+            // they throw offline rather than returning false — so the
+            // "needs-merge-confidence-api" reason belongs there, never here.
+            unevaluatable.push({ matcher: key, requiredFields, reason: "missing-input-field" });
+        }
+    }
+    return {
+        index,
+        rule,
+        matched: ruleResult.matched,
+        matchedBy,
+        decidedBy,
+        unevaluatable,
+        ...(ruleResult.contributedConfig
+            ? { contributedConfig: ruleResult.contributedConfig }
+            : {}),
+    };
+}
+// ---------------------------------------------------------------------------
+// Preview fallback: thin in-process glob-only matcher over the common static
+// keys. Deliberately approximate — only reached when the worker is unavailable.
+// ---------------------------------------------------------------------------
+const PREVIEW_SUPPORTED = {
+    matchPackageNames: { field: "packageName" },
+    matchDepNames: { field: "depName" },
+    matchManagers: { field: "manager" },
+    matchDatasources: { field: "datasource" },
+    matchFileNames: { field: "packageFile" },
+    matchCategories: { field: "categories", array: true },
+};
+function escapeRegex(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function globEquals(pattern, value) {
+    if (!pattern.includes("*"))
+        return pattern === value;
+    const re = new RegExp(`^${pattern.split("*").map(escapeRegex).join(".*")}$`);
+    return re.test(value);
+}
+function globListMatches(patterns, value) {
+    if (!Array.isArray(patterns) || typeof value !== "string")
+        return false;
+    return patterns.some((p) => typeof p === "string" && globEquals(p, value));
+}
+function previewContext(packageRules, context) {
+    const supplied = suppliedFieldsOf(context);
+    const rules = packageRules.map((rule, index) => {
+        const matchedBy = [];
+        const decidedBy = [];
+        const unevaluatable = [];
+        let unmatched = false;
+        for (const key of Object.keys(rule)) {
+            if (!key.startsWith("match") && !key.startsWith("exclude"))
+                continue;
+            const supported = PREVIEW_SUPPORTED[key];
+            if (!supported) {
+                unevaluatable.push({
+                    matcher: key,
+                    requiredFields: [],
+                    reason: "matcher-error",
+                    error: "not evaluated in preview mode (worker unavailable)",
+                });
+                continue;
+            }
+            const value = context[supported.field];
+            const ok = supported.array
+                ? Array.isArray(value) &&
+                    value.some((v) => globListMatches(rule[key], v))
+                : globListMatches(rule[key], value);
+            if (ok) {
+                matchedBy.push(key);
+            }
+            else if (supplied.has(supported.field)) {
+                // Field supplied but didn't match → a trustworthy non-match.
+                decidedBy.push(key);
+                unmatched = true;
+            }
+            else {
+                // Field absent → can't decide (same distinction the faithful path makes).
+                unevaluatable.push({
+                    matcher: key,
+                    requiredFields: [supported.field],
+                    reason: "missing-input-field",
+                });
+            }
+        }
+        // Match only if no supported matcher rejected AND nothing was unevaluatable.
+        const matched = !unmatched && unevaluatable.length === 0;
+        return {
+            index,
+            rule,
+            matched,
+            matchedBy,
+            decidedBy,
+            unevaluatable,
+            ...(matched ? { contributedConfig: stripMatchers(rule) } : {}),
+        };
+    });
+    return { mergedConfig: { ...context }, rules };
+}
+function stripMatchers(rule) {
+    const out = {};
+    for (const [k, v] of Object.entries(rule)) {
+        if (k.startsWith("match") || k.startsWith("exclude"))
+            continue;
+        out[k] = v;
+    }
+    return out;
+}

package/dist/lib/packageRulesWorker.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Evaluates Renovate's real `packageRules` matchers against one or more
+ * dependency contexts in a worker thread, isolating the main-process cost of
+ * importing `renovate`'s matcher registry (which transitively pulls in the
+ * versioning subsystem, JSONata, etc.). The whole batch is evaluated in ONE
+ * worker round-trip, so `annotate_dry_run` with N updates pays at most one cold
+ * start.
+ *
+ * Same worker-isolation invariant as `migrate_config` / the merge worker: the
+ * main process never imports `renovate`. See ADR-0006.
+ *
+ * The worker REPLICATES `applyPackageRules`' loop (rather than calling it as a
+ * black box) so it can return per-rule / per-matcher provenance Renovate exposes
+ * nowhere; see `packageRulesWorkerImpl.ts`.
+ */
+export type MatcherResultValue = "null" | "true" | "false" | "threw";
+export interface MatcherResult {
+    /** The matcher's class name, e.g. `DepNameMatcher`. */
+    name: string;
+    result: MatcherResultValue;
+    /** Present only when `result === "threw"`. */
+    error?: string;
+}
+export interface PerRuleResult {
+    /** True iff no applicable matcher returned false and none threw. */
+    matched: boolean;
+    matchers: MatcherResult[];
+    /** The rule's contribution (match/exclude keys stripped, overrides applied). Present only when matched. */
+    contributedConfig?: Record<string, unknown>;
+}
+export interface PerContextResult {
+    /** Faithful merged config — bit-identical to applyPackageRules for matchConfidence-free configs. */
+    mergedConfig: Record<string, unknown>;
+    rules: PerRuleResult[];
+}
+export declare class PackageRulesTimeoutError extends Error {
+    readonly timeoutMs: number;
+    constructor(timeoutMs: number);
+}
+export interface RunPackageRulesOptions {
+    timeoutMs?: number;
+}
+/**
+ * Evaluate `packageRules` against each of `contexts`, returning one result per
+ * context (faithful merged config + per-rule provenance). Throws
+ * `PackageRulesTimeoutError` on timeout or a plain Error on worker failure — the
+ * caller (packageRulesAnalysis) catches and degrades to a preview fallback.
+ */
+export declare function runApplyPackageRules(packageRules: Record<string, unknown>[], contexts: Record<string, unknown>[], options?: RunPackageRulesOptions): Promise<PerContextResult[]>;

package/dist/lib/packageRulesWorker.js

@@ -0,0 +1,82 @@
+import { Worker } from "node:worker_threads";
+// First-call latency budget: ESM cold-load of renovate's matcher registry (which
+// pulls in the versioning subsystem) can take a couple of seconds on slow CI.
+// Each call spawns a fresh worker, so this budget covers the cold path.
+const DEFAULT_TIMEOUT_MS = 30_000;
+/**
+ * Worker entry, resolved per call. Overridable via
+ * `RENOVATE_MCP_PACKAGE_RULES_WORKER_ENTRY` so the test suite — which loads this
+ * module as TS source under `src/`, where the sibling compiled `.js` does not
+ * exist — can point at `dist/lib/packageRulesWorkerImpl.js` (built by `pretest`),
+ * and so a test can point it at a bogus path to exercise the fallback. In
+ * production, `import.meta.url` already resolves to `dist/lib/`.
+ */
+function workerEntry() {
+    return (process.env.RENOVATE_MCP_PACKAGE_RULES_WORKER_ENTRY ??
+        new URL("./packageRulesWorkerImpl.js", import.meta.url));
+}
+export class PackageRulesTimeoutError extends Error {
+    timeoutMs;
+    constructor(timeoutMs) {
+        super(`Renovate packageRules worker exceeded ${timeoutMs}ms`);
+        this.name = "PackageRulesTimeoutError";
+        this.timeoutMs = timeoutMs;
+    }
+}
+/**
+ * Evaluate `packageRules` against each of `contexts`, returning one result per
+ * context (faithful merged config + per-rule provenance). Throws
+ * `PackageRulesTimeoutError` on timeout or a plain Error on worker failure — the
+ * caller (packageRulesAnalysis) catches and degrades to a preview fallback.
+ */
+export async function runApplyPackageRules(packageRules, contexts, options = {}) {
+    // Nothing to evaluate: skip the worker cold start entirely. With no rules,
+    // every context's merged config is itself and no rule matched.
+    if (contexts.length === 0)
+        return [];
+    if (packageRules.length === 0) {
+        return contexts.map((ctx) => ({
+            mergedConfig: { ...ctx, packageRules: [] },
+            rules: [],
+        }));
+    }
+    const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const worker = new Worker(workerEntry(), {
+        workerData: { packageRules, contexts },
+        // Isolate the worker's stdio — importing renovate pulls in its logger, and
+        // nothing from the worker may leak onto the parent's stdout JSON-RPC channel.
+        stdout: true,
+        stderr: true,
+    });
+    let timer;
+    try {
+        const response = await new Promise((resolve, reject) => {
+            // First event wins. The `exit` handler must reject when it fires before
+            // a message/error/timeout — a worker that crashes or exits before
+            // posting would otherwise leave the promise pending until the timeout.
+            let settled = false;
+            const settle = (fn) => {
+                if (settled)
+                    return;
+                settled = true;
+                fn();
+            };
+            timer = setTimeout(() => settle(() => resolve("timeout")), timeoutMs);
+            worker.once("message", (msg) => settle(() => resolve(msg)));
+            worker.once("error", (err) => settle(() => reject(err)));
+            worker.once("exit", (code) => settle(() => reject(new Error(`packageRules worker exited (code ${code}) before returning a result`))));
+        });
+        if (response === "timeout") {
+            throw new PackageRulesTimeoutError(timeoutMs);
+        }
+        if (!response.ok) {
+            throw new Error(`Renovate packageRules evaluation failed: ${response.error}`);
+        }
+        return response.results;
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+        await worker.terminate().catch(() => undefined);
+    }
+}

package/dist/lib/packageRulesWorkerImpl.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/lib/packageRulesWorkerImpl.js

@@ -0,0 +1,107 @@
+import { parentPort, workerData } from "node:worker_threads";
+const { packageRules, contexts } = workerData;
+function asRecord(value) {
+    return value && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : undefined;
+}
+/** Mirror of Renovate's `removeMatchers` (dist/util/package-rules/index.js). */
+function removeMatchers(rule) {
+    for (const key of Object.keys(rule)) {
+        if (key.startsWith("match") || key.startsWith("exclude"))
+            delete rule[key];
+    }
+    return rule;
+}
+try {
+    const matchers = (await import("renovate/dist/util/package-rules/matchers.js")).default;
+    const { mergeChildConfig } = (await import("renovate/dist/config/utils.js"));
+    const { compile } = (await import("renovate/dist/util/template/index.js"));
+    const slugify = (await import("slugify")).default;
+    const results = [];
+    for (const context of contexts) {
+        // Renovate's applyPackageRules reads `config.packageRules` off the input.
+        let config = { ...context, packageRules };
+        const rules = [];
+        for (const rule of packageRules) {
+            const matcherResults = [];
+            let anyFalse = false;
+            let anyThrew = false;
+            for (const matcher of matchers) {
+                const name = matcher.constructor.name;
+                try {
+                    const verdict = await matcher.matches(config, rule);
+                    if (verdict === null || verdict === undefined) {
+                        matcherResults.push({ name, result: "null" });
+                    }
+                    else if (verdict) {
+                        matcherResults.push({ name, result: "true" });
+                    }
+                    else {
+                        matcherResults.push({ name, result: "false" });
+                        anyFalse = true;
+                    }
+                }
+                catch (err) {
+                    matcherResults.push({
+                        name,
+                        result: "threw",
+                        error: err instanceof Error ? err.message : String(err),
+                    });
+                    anyThrew = true;
+                }
+            }
+            const matched = !anyFalse && !anyThrew;
+            let contributedConfig;
+            if (matched) {
+                // Replicate the merge in dist/util/package-rules/index.js exactly so
+                // `mergedConfig` matches applyPackageRules. Overrides mutate `config`
+                // mid-loop, so a later rule sees an earlier rule's overrides.
+                const toApply = removeMatchers({ ...rule });
+                const force = asRecord(toApply.force);
+                if (config.groupSlug && rule.groupName && !rule.groupSlug) {
+                    toApply.groupSlug = slugify(String(rule.groupName), { lower: true });
+                }
+                if (force?.enabled === false ||
+                    (toApply.enabled === false && config.enabled !== false)) {
+                    config.skipReason = "package-rules";
+                }
+                if (force?.enabled || toApply.enabled) {
+                    delete config.skipReason;
+                    delete config.skipStage;
+                }
+                if (typeof toApply.overrideDatasource === "string" &&
+                    toApply.overrideDatasource !== config.datasource) {
+                    config.datasource = toApply.overrideDatasource;
+                }
+                if (typeof toApply.overrideDepName === "string" &&
+                    toApply.overrideDepName !== config.depName) {
+                    config.depName = compile(toApply.overrideDepName, config);
+                }
+                if (typeof toApply.overridePackageName === "string" &&
+                    toApply.overridePackageName !== config.packageName) {
+                    config.packageName = compile(toApply.overridePackageName, config);
+                }
+                if (typeof toApply.sourceUrl === "string") {
+                    toApply.sourceUrl = compile(toApply.sourceUrl, config);
+                }
+                delete toApply.overrideDatasource;
+                delete toApply.overrideDepName;
+                delete toApply.overridePackageName;
+                contributedConfig = structuredClone(toApply);
+                config = mergeChildConfig(config, toApply);
+            }
+            rules.push({
+                matched,
+                matchers: matcherResults,
+                ...(contributedConfig ? { contributedConfig } : {}),
+            });
+        }
+        results.push({ mergedConfig: config, rules });
+    }
+    parentPort.postMessage({ ok: true, results });
+}
+catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    parentPort.postMessage({ ok: false, error: message });
+}

package/dist/lib/version.d.ts

@@ -1,4 +1,4 @@
-export declare const SERVER_VERSION = "1.2.0";
+export declare const SERVER_VERSION = "1.3.0";
 export type BuildMode = "local" | "released";
 export interface VersionInfo {
     version: string;

package/dist/lib/version.js

@@ -1,5 +1,5 @@
 import { fileURLToPath } from "node:url";
-export const SERVER_VERSION = "1.2.0"; // x-release-please-version
+export const SERVER_VERSION = "1.3.0"; // x-release-please-version
 // "released" = the server is running from a `node_modules/` install (global
 // `npm i -g`, project-local `npm i`, or `npx renovate-mcp`). Anything else —
 // most commonly an MCP config of `{"command": "node", "args": [".../dist/index.js"]}`

package/dist/tools/annotateDryRun.d.ts

@@ -0,0 +1,2 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerAnnotateDryRun(server: McpServer): void;

package/dist/tools/annotateDryRun.js

@@ -0,0 +1,248 @@
+import { promises as fs } from "node:fs";
+import { z } from "zod";
+import { locateConfig } from "../lib/configLocations.js";
+import { resolveConfig } from "../lib/presetResolver.js";
+import { identityKey } from "../lib/dryRunDiff.js";
+import { analyzePackageRules, MATCHER_META, } from "../lib/packageRulesAnalysis.js";
+import { configRecord, endpointString, pathString, reportRecord } from "../lib/inputLimits.js";
+const FAITHFUL_DISCLAIMER = "Each update is attributed using Renovate's real matchers (run in a worker thread) against the facts present in the dry_run report. Matchers needing data the report doesn't carry are reported under each update's `unevaluatable` and aggregated in `fieldGaps`, NOT as non-matches. matchConfidence needs the merge-confidence API (unevaluatable offline); matchJsonata is advisory. Run dry_run for full-fidelity resolution.";
+const PREVIEW_DISCLAIMER = "The faithful matcher worker was unavailable, so this used an approximate glob-only preview (matchPackageNames / matchDepNames / matchManagers / matchDatasources / matchFileNames / matchCategories only); rules using any other matcher are reported as unevaluatable. Run dry_run for authoritative output.";
+// Matcher-relevant fields we try to lift off each report upgrade entry.
+const CONTEXT_FIELDS = [
+    "depName", "packageName", "datasource", "manager", "depType", "depTypes",
+    "currentValue", "currentVersion", "lockedVersion", "versioning", "packageFile",
+    "lockFiles", "categories", "sourceUrl", "updateType", "newValue", "newVersion",
+    "currentVersionTimestamp", "registryUrls", "baseBranch", "repository", "isBump",
+];
+function extractReport(input) {
+    if (input && typeof input === "object" && !Array.isArray(input)) {
+        const obj = input;
+        if ("report" in obj && obj.report && typeof obj.report === "object") {
+            return obj.report;
+        }
+    }
+    return input;
+}
+function readRecord(node, key) {
+    if (!node || typeof node !== "object")
+        return null;
+    const value = node[key];
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return null;
+    return value;
+}
+function readArray(node, key) {
+    if (!node || typeof node !== "object")
+        return null;
+    const value = node[key];
+    return Array.isArray(value) ? value : null;
+}
+/** Walk repositories[*].branches[*].upgrades[] and lift matcher-relevant facts. */
+function collectUpdateEntries(report) {
+    const out = [];
+    const repositories = readRecord(report, "repositories");
+    if (!repositories)
+        return out;
+    for (const repo of Object.values(repositories)) {
+        const branches = readArray(repo, "branches");
+        if (!branches)
+            continue;
+        for (const branch of branches) {
+            const upgrades = readArray(branch, "upgrades");
+            if (!upgrades)
+                continue;
+            for (const upgrade of upgrades) {
+                if (!upgrade || typeof upgrade !== "object")
+                    continue;
+                const u = upgrade;
+                const manager = typeof u.manager === "string" ? u.manager : "";
+                const depName = typeof u.depName === "string" ? u.depName : "";
+                if (!manager || !depName)
+                    continue;
+                const packageFile = typeof u.packageFile === "string" ? u.packageFile : "";
+                const context = {};
+                for (const field of CONTEXT_FIELDS) {
+                    if (u[field] !== undefined)
+                        context[field] = u[field];
+                }
+                out.push({
+                    display: {
+                        manager,
+                        packageFile,
+                        depName,
+                        currentVersion: u.currentVersion ?? u.currentValue,
+                        newVersion: u.newVersion ?? u.newValue,
+                        updateType: u.updateType,
+                    },
+                    context,
+                });
+            }
+        }
+    }
+    return out;
+}
+async function readReportPath(reportPath) {
+    let raw;
+    try {
+        raw = await fs.readFile(reportPath, "utf8");
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return { ok: false, error: `Could not read reportPath (\`${reportPath}\`): ${msg}.` };
+    }
+    try {
+        return { ok: true, value: JSON.parse(raw) };
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return { ok: false, error: `reportPath (\`${reportPath}\`) is not valid JSON: ${msg}.` };
+    }
+}
+export function registerAnnotateDryRun(server) {
+    server.registerTool("annotate_dry_run", {
+        title: "Attribute dry_run updates to packageRules",
+        description: "Given a `dry_run` report and a config, attribute EACH proposed update to the `packageRules` that matched it — answering \"which of my rules produced these updates?\". Stateless and offline: run `dry_run` first, then pass its report here (inline `report` or `reportPath`, same shapes as `dry_run_diff`) plus a config source (`repoPath` or `configContent`). Each update is matched with Renovate's REAL matchers in a worker thread against the facts present in the report; fields the report doesn't carry (e.g. datasource, depType) are reported under each update's `unevaluatable` and aggregated in `fieldGaps` rather than silently treated as non-matches. `rulesNeverMatched` flags likely-dead rules. Deprecated matcher keys are warned about — run migrate_config first. Run dry_run for full-fidelity confirmation.",
+        inputSchema: {
+            report: reportRecord("A Renovate dry-run report — the raw report (`{ repositories }`) or a full `dry_run` summary (`{ report }`); the tool unwraps `report` automatically. Use instead of reportPath.").optional(),
+            reportPath: pathString("Absolute path to a JSON file containing the report (pair with `dry_run`'s reportOutputPath). Use instead of report.").optional(),
+            repoPath: pathString("Absolute path to the repository root; the tool locates and expands its renovate config to get the packageRules. Use instead of configContent.").optional(),
+            configContent: configRecord("Inline config object whose packageRules to attribute against. Use instead of repoPath.").optional(),
+            externalPresets: z
+                .boolean()
+                .optional()
+                .describe("When true, fetch external presets (github>, gitlab>) so their packageRules are included — same semantics as resolve_config. Default false."),
+            endpoint: endpointString("API base URL for github>/gitlab> fetches — same semantics as resolve_config.").optional(),
+            platform: z
+                .enum(["github", "gitlab"])
+                .optional()
+                .describe("Platform flavour of `endpoint` — same semantics as resolve_config."),
+        },
+    }, async ({ report, reportPath, repoPath, configContent, externalPresets, endpoint, platform }) => {
+        if (!report && !reportPath) {
+            return {
+                isError: true,
+                content: [{ type: "text", text: "Provide either report or reportPath (run dry_run first)." }],
+            };
+        }
+        if (!repoPath && !configContent) {
+            return {
+                isError: true,
+                content: [{ type: "text", text: "Provide a config source: either repoPath or configContent." }],
+            };
+        }
+        // Resolve the report.
+        let reportValue;
+        let reportSource;
+        if (reportPath) {
+            const res = await readReportPath(reportPath);
+            if (!res.ok)
+                return { isError: true, content: [{ type: "text", text: res.error }] };
+            reportValue = res.value;
+            reportSource = "reportPath";
+        }
+        else {
+            reportValue = report;
+            reportSource = "inline";
+        }
+        // Resolve the config's effective packageRules.
+        let source;
+        let sourcePath;
+        if (configContent) {
+            source = configContent;
+        }
+        else {
+            const located = await locateConfig(repoPath);
+            if (!located) {
+                return { content: [{ type: "text", text: `No Renovate configuration found in ${repoPath}.` }] };
+            }
+            source = located.config;
+            sourcePath = located.relPath;
+        }
+        const { resolved, warnings: presetWarnings, presetsUnresolved } = await resolveConfig(source, {
+            fetchExternal: externalPresets ?? false,
+            endpoint,
+            platform,
+        });
+        const packageRules = Array.isArray(resolved.packageRules)
+            ? resolved.packageRules.filter((r) => !!r && typeof r === "object" && !Array.isArray(r))
+            : [];
+        // Collect + dedup updates (a dep can appear in multiple branches).
+        const entriesRaw = collectUpdateEntries(extractReport(reportValue));
+        const seen = new Set();
+        const entries = [];
+        for (const e of entriesRaw) {
+            const key = identityKey(e.display);
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            entries.push(e);
+        }
+        const analysis = await analyzePackageRules(packageRules, entries.map((e) => e.context));
+        const matchedIndices = new Set();
+        const annotations = entries.map((entry, i) => {
+            const ruleAnalysis = analysis.contexts[i]?.rules ?? [];
+            const matchedRules = ruleAnalysis
+                .filter((r) => r.matched)
+                .map((r) => {
+                matchedIndices.add(r.index);
+                return {
+                    index: r.index,
+                    rule: r.rule,
+                    matchedBy: r.matchedBy,
+                    ...(r.contributedConfig ? { contributedConfig: r.contributedConfig } : {}),
+                };
+            });
+            const unevaluatable = ruleAnalysis.flatMap((r) => r.unevaluatable.map((u) => ({ ruleIndex: r.index, ...u })));
+            return { ...entry.display, matchedRules, unevaluatable };
+        });
+        const rulesNeverMatched = packageRules
+            .map((_, i) => i)
+            .filter((i) => !matchedIndices.has(i));
+        // fieldGaps: context fields referenced by the rules' matchers that no
+        // update in the report carried — the report shape didn't supply them.
+        const presentFields = new Set();
+        for (const e of entries)
+            for (const f of Object.keys(e.context))
+                presentFields.add(f);
+        const usedFields = new Set();
+        const metaByKey = new Map(Object.values(MATCHER_META).map((m) => [m.key, m]));
+        for (const rule of packageRules) {
+            for (const key of Object.keys(rule)) {
+                const meta = metaByKey.get(key);
+                if (meta)
+                    for (const f of meta.requiredAnyOf)
+                        usedFields.add(f);
+            }
+        }
+        const fieldGaps = [...usedFields].filter((f) => !presentFields.has(f)).sort();
+        const warnings = [...analysis.warnings, ...presetWarnings.map((w) => `${w.preset}: ${w.message}`)];
+        if (presetsUnresolved.length > 0) {
+            warnings.push(`${presetsUnresolved.length} preset(s) could not be expanded, so preset-provided packageRules may be missing: ${presetsUnresolved
+                .map((p) => p.preset)
+                .join(", ")}.`);
+        }
+        if (packageRules.length === 0)
+            warnings.push("The resolved config has no packageRules.");
+        if (entries.length === 0)
+            warnings.push("The report contained no proposed updates to annotate.");
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({
+                        ...(sourcePath ? { configPath: sourcePath } : {}),
+                        matchQuality: analysis.matchQuality,
+                        disclaimer: analysis.matchQuality === "faithful" ? FAITHFUL_DISCLAIMER : PREVIEW_DISCLAIMER,
+                        reportSource,
+                        ruleCount: packageRules.length,
+                        updateCount: entries.length,
+                        annotations,
+                        rulesNeverMatched,
+                        fieldGaps,
+                        warnings,
+                    }, null, 2),
+                },
+            ],
+        };
+    });
+}

package/dist/tools/testPackageRules.d.ts

@@ -0,0 +1,2 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerTestPackageRules(server: McpServer): void;

package/dist/tools/testPackageRules.js

@@ -0,0 +1,135 @@
+import { z } from "zod";
+import { locateConfig } from "../lib/configLocations.js";
+import { resolveConfig } from "../lib/presetResolver.js";
+import { analyzePackageRules } from "../lib/packageRulesAnalysis.js";
+import { configRecord, endpointString, pathString } from "../lib/inputLimits.js";
+const FAITHFUL_DISCLAIMER = "Rules are evaluated with Renovate's real matchers (run in a worker thread), so match decisions are faithful for the fields you supplied. Matchers needing post-lookup data you didn't supply (matchUpdateTypes, matchCurrentVersion, matchNewValue, matchCurrentAge) or the merge-confidence API (matchConfidence) are reported under `unevaluatable`, NOT as non-matches. matchJsonata results are advisory (the expression may read fields you didn't supply). Run dry_run for full-fidelity resolution.";
+const PREVIEW_DISCLAIMER = "The faithful matcher worker was unavailable, so this used an approximate glob-only preview (matchPackageNames / matchDepNames / matchManagers / matchDatasources / matchFileNames / matchCategories only); rules using any other matcher are reported as unevaluatable. Run dry_run for authoritative output.";
+const optString = (description) => z.string().max(2048).optional().describe(description);
+const optStringArray = (description) => z.array(z.string().max(2048)).max(256).optional().describe(description);
+export function registerTestPackageRules(server) {
+    server.registerTool("test_package_rules", {
+        title: "Test which packageRules match a dependency",
+        description: "Offline \"what-if\": given a hypothetical dependency context and a config, report which `packageRules` match (in order), which matcher decided each, and what each matched rule contributes. Answers \"why didn't my rule match?\". Rules are evaluated with Renovate's REAL matchers in a worker thread (faithful), classified against the fields you actually supplied — a matcher that needs a field you didn't pass is reported as `unevaluatable`, never silently treated as a non-match. Matchers needing post-lookup data (matchUpdateTypes, matchCurrentVersion, matchNewValue, matchCurrentAge) or the merge-confidence API (matchConfidence) are unevaluatable offline; matchJsonata is advisory. Pass either `repoPath` (reads + expands the repo's config) or `configContent` (an inline config); `externalPresets`/`endpoint`/`platform` opt into external preset expansion so `extends`-provided rules are included (same semantics as resolve_config). Deprecated matcher keys (matchPackagePatterns, …) are warned about — run migrate_config first. Run dry_run for full-fidelity confirmation.",
+        inputSchema: {
+            repoPath: pathString("Absolute path to the repository root. The tool locates and expands the repo's renovate config automatically.").optional(),
+            configContent: configRecord("Inline config object whose packageRules to test — use instead of repoPath.").optional(),
+            externalPresets: z
+                .boolean()
+                .optional()
+                .describe("When true, fetch external presets (github>, gitlab>) over HTTPS so their packageRules are included — same credentials/behaviour as resolve_config. Default false."),
+            endpoint: endpointString("API base URL for github>/gitlab> fetches — same semantics as resolve_config.").optional(),
+            platform: z
+                .enum(["github", "gitlab"])
+                .optional()
+                .describe("Platform flavour of `endpoint` — same semantics as resolve_config."),
+            // Synthetic dependency context. All optional; supply what you're testing.
+            depName: optString("Dependency name (matchDepNames; static)."),
+            packageName: optString("Fully-qualified package name (matchPackageNames; static)."),
+            datasource: optString("Datasource, e.g. npm/docker/github-releases (matchDatasources; static)."),
+            manager: optString("Manager, e.g. npm/dockerfile (matchManagers; static)."),
+            depType: optString("Dependency type, e.g. dependencies/devDependencies (matchDepTypes; static)."),
+            depTypes: optStringArray("Multiple dependency types (matchDepTypes; static)."),
+            currentValue: optString("Current version constraint from the file, e.g. ^1.2.0 (matchCurrentValue; static)."),
+            currentVersion: optString("Resolved current version, e.g. 1.2.3 (matchCurrentVersion; normally known only after a datasource lookup)."),
+            lockedVersion: optString("Locked version from a lockfile (matchCurrentVersion; post-lookup)."),
+            versioning: optString("Versioning scheme, e.g. npm/semver/docker (affects matchCurrentVersion)."),
+            packageFile: optString("Package file path (matchFileNames; static)."),
+            lockFiles: optStringArray("Lock file paths (matchFileNames; static)."),
+            categories: optStringArray("Manager categories, e.g. js/docker (matchCategories; static)."),
+            repository: optString("Repository slug, e.g. owner/repo (matchRepositories; static)."),
+            baseBranch: optString("Base branch name (matchBaseBranches; static)."),
+            registryUrls: optStringArray("Registry URLs (matchRegistryUrls; static)."),
+            sourceUrl: optString("Source repository URL (matchSourceUrls; static)."),
+            newValue: optString("Proposed new version constraint (matchNewValue; post-lookup)."),
+            updateType: optString("Update type: major/minor/patch/pin/digest/… (matchUpdateTypes; post-lookup)."),
+            isBump: z.boolean().optional().describe("Whether this is a range bump (matchUpdateTypes; post-lookup)."),
+            currentVersionTimestamp: optString("Release timestamp of the current version (matchCurrentAge; post-lookup)."),
+            mergeConfidenceLevel: optString("Merge-confidence level (matchConfidence; needs the merge-confidence API — unevaluatable offline)."),
+        },
+    }, async ({ repoPath, configContent, externalPresets, endpoint, platform, ...ctx }) => {
+        if (!repoPath && !configContent) {
+            return {
+                isError: true,
+                content: [{ type: "text", text: "Provide either repoPath or configContent." }],
+            };
+        }
+        let source;
+        let sourcePath;
+        if (configContent) {
+            source = configContent;
+        }
+        else {
+            const located = await locateConfig(repoPath);
+            if (!located) {
+                return {
+                    content: [{ type: "text", text: `No Renovate configuration found in ${repoPath}.` }],
+                };
+            }
+            source = located.config;
+            sourcePath = located.relPath;
+        }
+        // Expand `extends` so preset-provided packageRules are included, then test
+        // against the effective set.
+        const { resolved, warnings: presetWarnings, presetsUnresolved } = await resolveConfig(source, {
+            fetchExternal: externalPresets ?? false,
+            endpoint,
+            platform,
+        });
+        const packageRules = Array.isArray(resolved.packageRules)
+            ? resolved.packageRules.filter((r) => !!r && typeof r === "object" && !Array.isArray(r))
+            : [];
+        // Build the synthetic dependency context from supplied fields only.
+        const context = {};
+        for (const [k, v] of Object.entries(ctx)) {
+            if (v !== undefined)
+                context[k] = v;
+        }
+        const analysis = await analyzePackageRules(packageRules, [context]);
+        const result = analysis.contexts[0] ?? { mergedConfig: {}, rules: [] };
+        const matchedRules = result.rules
+            .filter((r) => r.matched)
+            .map((r) => ({
+            index: r.index,
+            rule: r.rule,
+            matchedBy: r.matchedBy,
+            ...(r.contributedConfig ? { contributedConfig: r.contributedConfig } : {}),
+        }));
+        const unmatchedRules = result.rules
+            .filter((r) => !r.matched)
+            .map((r) => ({ index: r.index, rule: r.rule, decidedBy: r.decidedBy }));
+        const unevaluatable = result.rules.flatMap((r) => r.unevaluatable.map((u) => ({ ruleIndex: r.index, ...u })));
+        const effectiveConfig = { ...result.mergedConfig };
+        delete effectiveConfig.packageRules;
+        const warnings = [...analysis.warnings, ...presetWarnings.map((w) => `${w.preset}: ${w.message}`)];
+        if (presetsUnresolved.length > 0) {
+            warnings.push(`${presetsUnresolved.length} preset(s) could not be expanded, so preset-provided packageRules may be missing: ${presetsUnresolved
+                .map((p) => p.preset)
+                .join(", ")}. See resolve_config for details.`);
+        }
+        if (packageRules.length === 0) {
+            warnings.push("The resolved config has no packageRules to test.");
+        }
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({
+                        ...(sourcePath ? { path: sourcePath } : {}),
+                        matchQuality: analysis.matchQuality,
+                        disclaimer: analysis.matchQuality === "faithful"
+                            ? FAITHFUL_DISCLAIMER
+                            : PREVIEW_DISCLAIMER,
+                        ruleCount: packageRules.length,
+                        matchedRuleCount: matchedRules.length,
+                        matchedRules,
+                        unmatchedRules,
+                        unevaluatable,
+                        effectiveConfig,
+                        warnings,
+                    }, null, 2),
+                },
+            ],
+        };
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "renovate-mcp",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "MCP server for designing Renovate configurations interactively.",
   "type": "module",
   "bin": {
@@ -64,7 +64,7 @@
     "json5": "^2.2.3",
     "jsonata": "2.2.1",
     "jsonc-parser": "^3.3.1",
-    "renovate": "^43.233.4",
+    "renovate": "^43.245.0",
     "smol-toml": "^1.6.1",
     "yaml": "^2.9.0",
     "zod": "^4.0.0"