renovate-mcp 1.1.1 → 1.3.0

package/README.md

@@ -31,6 +31,7 @@ Restart your client and try the prompt: *"List the namespaces available under `r
 ## What you can do
 
 - **Read and explain configs** — locate the active `renovate.json*`, expand every `extends` preset offline, and trace which preset set each field.
+- **Discover presets from intent** — describe what you want ("automerge patches, group dev deps") and get ranked built-in (and your own local-repo) presets, plus a draft config skeleton when nothing fits.
 - **Preview custom managers** before running Renovate — regex and JSONata, with file/line hits and extracted dep info.
 - **Validate and lint** — schema validation plus a semantic lint pass for Renovate-specific footguns (unwrapped regexes, unknown manager names, deprecated keys).
 - **Dry-run** against a local checkout or a remote GitHub/GitLab — see exactly which PRs Renovate would open.
@@ -38,21 +39,24 @@ Restart your client and try the prompt: *"List the namespaces available under `r
 
 ## Tools & resources
 
-Thirteen 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 |
 | --- | --- |
 | [`check_setup`](docs/tools.md#check_setup) | Report Renovate CLI + validator availability, versions, install hints, and a `platformContext` block for env diagnosis. Also runs at startup. Pass an optional `repoPath` to add a `repoContext` block diagnosing the repo's git origin, config endpoint/platform, endpoint reachability, and token coverage. |
 | [`get_version`](docs/tools.md#get_version) | Report the renovate-mcp server version and whether it's a released or local/dev build. |
 | [`read_config`](docs/tools.md#read_config) | Locate and parse a repo's Renovate config in Renovate's own discovery order. |
+| [`suggest_presets`](docs/tools.md#suggest_presets) | Search built-in (and optional local-repo) presets by natural-language intent; ranks matches and sketches an unvalidated draft config skeleton for multi-facet or weakly-covered intents. Offline. |
 | [`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. |
@@ -64,7 +68,7 @@ Thirteen tools and three resource templates. Each tool name below links to its f
 - **Linux or macOS.** Windows is not supported — `package.json` declares `"os": ["darwin", "linux"]`, so `npm i` surfaces an `EBADPLATFORM` warning on Windows and the server exits with a clear stderr message at startup. Use WSL2 or a Linux/macOS host instead.
 - **Node.js ≥ 24** (aligns with Renovate's own engine requirement).
 
-Renovate ships bundled — the `renovate` package is a runtime dependency, so `validate_config`, `dry_run`, and `write_config` work out of the box with no separate install. The offline tools (`read_config`, `resolve_config`, `explain_config`, `resolve_config_diff`, `preview_custom_manager`, `lint_config`) never spawn Renovate at all.
+Renovate ships bundled — the `renovate` package is a runtime dependency, so `validate_config`, `dry_run`, and `write_config` work out of the box with no separate install. The offline tools (`read_config`, `suggest_presets`, `resolve_config`, `explain_config`, `resolve_config_diff`, `preview_custom_manager`, `lint_config`) never spawn Renovate at all.
 
 **Optional env vars:**
 
@@ -125,11 +129,12 @@ Once the server is wired up, try prompts like these. Written for Claude but work
 - "Resolve my config and list anything that landed in `presetsUnresolved`, with the reason for each."
 - "Why is my `prCreation` set to `not-pending`? Use `explain_config` to trace which preset set it."
 
-**Browsing presets**
+**Discovering & browsing presets**
 
+- "I want to automerge patch and minor updates and group my dev dependencies — suggest presets for that, search my `../renovate-presets` repo too, and draft a config I can validate."
 - "List the presets in the `config` namespace." (uses the `renovate://presets/config` sub-resource — cheaper than pulling the whole index)
 - "What does `config:recommended` actually enable? Show me its expanded JSON."
-- "Find a built-in preset that pins GitHub Actions digests."
+- "Find a built-in preset that pins GitHub Actions digests." (or use `suggest_presets` with that intent)
 
 **Self-hosted GitLab / GitHub Enterprise** (env set per [Platform setup](#platform-setup))
 

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

@@ -8,9 +8,12 @@ import { registerLintConfig } from "./tools/lintConfig.js";
 import { registerResolveConfig } from "./tools/resolveConfig.js";
 import { registerExplainConfig } from "./tools/explainConfig.js";
 import { registerResolveConfigDiff } from "./tools/resolveConfigDiff.js";
+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";
@@ -32,16 +35,19 @@ const BASE_INSTRUCTIONS = [
     "",
     "Workflow:",
     "  1. read_config            — inspect the current config in a repo",
-    "  2. resolve_config         — expand built-in presets to see what a config actually becomes (offline)",
-    "  3. explain_config         — inverse of resolve_config: trace which preset set each field (offline)",
-    "  4. 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",
-    "  5. preview_custom_manager — iterate on a regex-based customManagers entry; shows file/line hits and extracted deps",
-    "  6. validate_config        — check a proposed config against Renovate's schema",
-    "  7. lint_config            — semantic lint pass: catches Renovate-specific footguns schema validation misses (e.g. malformed /…/ regex patterns)",
-    "  8. dry_run                — preview what Renovate would actually do (no PRs)",
-    "  9. dry_run_diff           — semantic diff between two dry_run reports (added/removed/changed updates)",
-    " 10. migrate_config         — apply Renovate's built-in migrations (deprecated keys → current schema) and return the migrated config",
-    " 11. write_config           — save the agreed-upon config (validates first)",
+    "  2. suggest_presets        — go from a natural-language intent to candidate built-in/local presets + an unvalidated draft skeleton (offline); then validate_config + lint_config",
+    "  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. 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.",
@@ -64,11 +70,14 @@ registerReadConfig(server);
 registerResolveConfig(server);
 registerExplainConfig(server);
 registerResolveConfigDiff(server);
+registerSuggestPresets(server);
 registerPreviewCustomManager(server);
 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/inputLimits.d.ts

@@ -4,6 +4,7 @@ export declare const TOKEN_MAX_BYTES = 1024;
 export declare const ENDPOINT_MAX_BYTES = 2048;
 export declare const REPOSITORY_MAX_BYTES = 256;
 export declare const FILENAME_MAX_BYTES = 512;
+export declare const QUERY_MAX_BYTES = 2048;
 export declare const CONFIG_JSON_MAX_BYTES = 1000000;
 export declare const REPORT_JSON_MAX_BYTES = 10000000;
 export declare const HOST_RULES_MAX_ITEMS = 256;
@@ -13,6 +14,7 @@ export declare const tokenString: (description: string) => z.ZodString;
 export declare const endpointString: (description: string) => z.ZodString;
 export declare const repositoryString: (description: string) => z.ZodString;
 export declare const filenameString: (description: string) => z.ZodString;
+export declare const queryString: (description: string) => z.ZodString;
 export declare const configRecord: (description: string) => z.ZodRecord<z.ZodString, z.ZodUnknown>;
 export declare const reportRecord: (description: string) => z.ZodRecord<z.ZodString, z.ZodUnknown>;
 export declare const hostRuleRecord: (description: string) => z.ZodRecord<z.ZodString, z.ZodUnknown>;

package/dist/lib/inputLimits.js

@@ -9,6 +9,7 @@ export const TOKEN_MAX_BYTES = 1024;
 export const ENDPOINT_MAX_BYTES = 2048;
 export const REPOSITORY_MAX_BYTES = 256;
 export const FILENAME_MAX_BYTES = 512;
+export const QUERY_MAX_BYTES = 2048;
 export const CONFIG_JSON_MAX_BYTES = 1_000_000;
 export const REPORT_JSON_MAX_BYTES = 10_000_000;
 export const HOST_RULES_MAX_ITEMS = 256;
@@ -18,6 +19,7 @@ export const tokenString = (description) => z.string().max(TOKEN_MAX_BYTES).desc
 export const endpointString = (description) => z.string().max(ENDPOINT_MAX_BYTES).describe(description);
 export const repositoryString = (description) => z.string().max(REPOSITORY_MAX_BYTES).describe(description);
 export const filenameString = (description) => z.string().max(FILENAME_MAX_BYTES).describe(description);
+export const queryString = (description) => z.string().min(1).max(QUERY_MAX_BYTES).describe(description);
 const refineJsonSize = (limit) => (value) => {
     try {
         return JSON.stringify(value).length <= limit;

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[]>;