[Linter] Add gracePeriodInDays option to use-recent-api-versions to prevent recommending undeployable API versions

[Copilot]

The use-recent-api-versions rule can recommend API versions that are present in bicep-types-az specs but not yet deployed by the resource provider in all regions, causing deployment failures after users follow the lint suggestion.

Changes

• New gracePeriodInDays config option (default: 0, fully backward-compatible): excludes API versions newer than N days from the recommended versions list, giving RPs time to complete regional rollout
• Current-version protection: if the user is already using a version within the grace period, no diagnostic is emitted (avoids spurious "downgrade" suggestions)
• Fallback behavior: if all known versions fall within the grace period, the filter is lifted so there is always at least one recommendation

Configuration

// bicepconfig.json
{
  "analyzers": {
    "core": {
      "rules": {
        "use-recent-api-versions": {
          "level": "warning",
          "gracePeriodInDays": 60  // don't recommend versions < 60 days old
        }
      }
    }
  }
}

Implementation

• GetAcceptableApiVersions filters eligible versions through FilterOldEnough before running the existing recency/stable/preview selection logic
• AnalyzeApiVersion short-circuits to null (pass) when the actual version is itself within the grace period
• gracePeriodInDays is threaded through AnalyzeInternal → AnalyzeResource / AnalyzeFunctionCall → AnalyzeApiVersion → GetAcceptableApiVersions

Original prompt

---

This section details on the original issue you should resolve

<issue_title>[Linter] use-recent-api-versions recommends API versions that are not deployable</issue_title>
<issue_description>Bicep version
Bicep CLI version 0.34.44 (0439eb6484)

Describe the bug
There is a gap between when API version specs are published to azure-rest-api-specs (and auto-generated into bicep-types-az) and when resource providers actually deploy support for those versions. The use-recent-api-versions linter rule does not account for this gap, so it can recommend API versions that fail on deployment.

Current examples:

• Microsoft.Search/searchServices@2025-05-01 — fails in eastus ([Microsoft.Search/searchServices]: Resource fails to deploy with API version 2025-05-01 bicep-types-az#2693)
• Microsoft.Insights/scheduledQueryRules@2026-03-01 — fails in eastus (Microsoft.Insights/scheduledQueryRules@2023-12-01 : missing bicep-types-az#2185)

This is a recurring pattern. Issues for scheduledQueryRules@2023-12-01 were filed across May–October 2024 (Azure/bicep-types-az#2183, Azure/bicep-types-az#2193, Azure/bicep-types-az#2318) and remain open. That version eventually became available in the RP, but the same pattern immediately recurred with @2026-03-01. Other resource types have been affected as well, including Microsoft.ApiManagement/service (Azure/bicep-types-az#2301).

The practical impact is that users update to the linter-recommended version, deployments fail, and they must roll back and add #disable-next-line use-recent-api-versions suppressions.

Note: my bicepconfig.json uses maxAllowedAgeInDays: 45, which is more aggressive than the 730-day default. This increases the likelihood of hitting the issue, but does not change the underlying problem — the linter will recommend undeployable versions regardless of the threshold if the currently-used version is old enough.

To Reproduce

1. Configure use-recent-api-versions with a maxAllowedAgeInDays value that flags the current version as stale
2. Create a Bicep file with Microsoft.Search/searchServices@2025-02-01-preview
3. Observe the linter warning recommending @2025-05-01
4. Update to the recommended version
5. Deploy to eastus
6. Deployment fails with NoRegisteredProviderFound

Additional context
A possible mitigation would be for the linter rule to apply a grace period after a type version first appears in bicep-types-az before recommending it, giving resource providers time to complete deployment. Alternatively, the linter documentation could note that recommended versions may not yet be deployable in all regions.
</issue_description>

Comments on the Issue (you are @copilot in this section)

• Fixes [Linter] use-recent-api-versions recommends API versions that are not deployable #19143

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

Microsoft Reviewers: Open in CodeFlow

[github-actions]

Test this change out locally with the following install scripts (Action run 22927094989)

VSCode

• Mac/Linux

  bash <(curl -Ls https://aka.ms/bicep/nightly-vsix.sh) --run-id 22927094989

• Windows

  iex "& { $(irm https://aka.ms/bicep/nightly-vsix.ps1) } -RunId 22927094989"

Azure CLI

• Mac/Linux

  bash <(curl -Ls https://aka.ms/bicep/nightly-cli.sh) --run-id 22927094989

• Windows

  iex "& { $(irm https://aka.ms/bicep/nightly-cli.ps1) } -RunId 22927094989"