Link Checker: Allow relative links in configurable file path patterns

[Copilot]

The link checker's checkLinkGuidance mode unconditionally rejected relative links, making it impractical for .github/ markdown files (e.g. copilot instructions) that benefit from relative cross-references between files.

Changes

• Verify-Links.ps1: Added -allowRelativeLinksFile parameter. When provided, loads a list of glob patterns; pages whose paths match any pattern skip the relative-link restriction while still having all other link guidance enforced (http→https, uppercase anchors, locale checks). Defaults to (Join-Path $PSScriptRoot "allow-relative-links.txt") (i.e. the file next to the script). Glob-to-regex compilation is done once at load time for efficiency. Comment-line filtering correctly handles indented # comment lines.

  .\Verify-Links.ps1 -checkLinkGuidance $true -allowRelativeLinksFile eng/common/scripts/allow-relative-links.txt

• Verify-Links.ps1: Removed the ad-hoc instructions.md special case (previously added for copilot instruction files) — this is now handled generically via allow-relative-links.txt.

• verify-links.yml (DevOps template): Added AllowRelativeLinksFile parameter, defaulting to $(Build.SourcesDirectory)/eng/common/scripts/allow-relative-links.txt. Passed through to the script.

• eng/common/scripts/allow-relative-links.txt (new): Default config file placed next to Verify-Links.ps1 in eng/common/scripts/ so it syncs across eng/common to all Azure SDK repos. Pre-populated with .github/** (all files under the .github folder, e.g. copilot instructions) and eng/** (all files under the eng folder, e.g. engineering system scripts and templates). Repo-specific patterns should be added per-repo as needed.

• eng/common-tests/Verify-Links-AllowRelativeLinks.Tests.ps1 (new): Pester tests for the pattern-matching logic.

Config file format

One glob pattern per line; # lines are comments (indented comments are also supported). Both * (single segment) and ** (multi-segment) wildcards are supported. A leading ** is not required — patterns are matched as substrings against the full path.

# Allow relative links for all files under the .github folder (e.g. copilot instructions).
.github/**
# Allow relative links for all files under the eng folder (e.g. engineering system scripts and templates).
eng/**

# Example: allow relative links in specs directories (repo-specific)
# **/specs/**

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.

[weshaggard]

/azp run azure-sdk-tools - sync - eng-common

[weshaggard]

@copilot

The filtering logic for comment lines checks StartsWith("#") without trimming leading whitespace. This contradicts the parameter docs (“lines beginning with '#' are treated as comments”) and will treat lines like ' # comment' as patterns. Consider using TrimStart() (or checking after Trim()) before StartsWith('#') so indented comment lines are ignored as intended.

This converts each glob pattern to a regex on every page check. If many pages are scanned, this is avoidable overhead. Consider precomputing and storing normalized/compiled regex objects once when loading $allowRelativeLinkPatterns, then simply iterating the compiled regex list in Test-PageUriMatchesRelativeLinkPattern.

The default path is built via string concatenation with a hard-coded /. While it often works, it’s more robust/cross-platform to build paths with Join-Path (or [System.IO.Path]::Combine) to avoid separator quirks and improve readability.

The comment says this allowlist is for “all markdown files under the .github folder”, but the glob .github/** is not restricted to markdown, and eng/** broadens the scope further without explanation. Please update the comment(s) to match the actual behavior, or (if intended) narrow the patterns (e.g., .github//*.md) and document why eng/ is included.

[Copilot]

@copilot

The filtering logic for comment lines checks StartsWith("#") without trimming leading whitespace. This contradicts the parameter docs (“lines beginning with '#' are treated as comments...

Done in 1359805:

• Trim before # check: All three filter expressions now use $_.Trim().StartsWith("#") so indented comment lines like # comment are correctly ignored.
• Precomputed regexes: Glob-to-regex conversion now happens once at load time. $allowRelativeLinkRegexes stores an array of @{ Pattern; Regex } hashtables (compiled [Regex] objects). Test-PageUriMatchesRelativeLinkPattern simply iterates the precomputed list.
• Join-Path: The allowRelativeLinksFile parameter default now uses (Join-Path $PSScriptRoot "allow-relative-links.txt").
• eng/** removed: Dropped from allow-relative-links.txt; comment updated from "all markdown files" to "all files" to accurately reflect the scope of .github/**.

[weshaggard]

@copilot I still want eng/** in the allowed list I just wanted the comment to be updated.

[Copilot]

@copilot I still want eng/** in the allowed list I just wanted the comment to be updated.

Done in 4e126a4. Added eng/** back with an updated comment: "Allow relative links for all files under the eng folder (e.g. engineering system scripts and templates)."

[weshaggard]

/azp run azure-sdk-tools - sync - eng-common

[azure-pipelines]

Azure Pipelines successfully started running 1 pipeline(s).

[azure-sdk]

The following pipelines have been queued for testing:
java - template
java - template - tests
js - template
net - template
net - template - tests
python - template
python - template - tests
You can sign off on the approval gate to test the release stage of each pipeline.
See eng/common workflow