[DocsVerifier] Improve error reporting and ignore paths to external repos

[gewarren]

Fixes #738.

[Copilot]

🟡 Changes recommended

Four moderate issues remain in path-source handling and redirect line-number mapping.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

Improves DocsVerifier diagnostics and external-content path handling.

Changes:

• Adds line-number reporting for redirect and path errors.
• Handles metadata paths under external content sources.
• Expands diagnostic and exclusion test coverage.

File summaries

File	Reviewed change
actions/docs-verifier/tests/GitHub.UnitTests/RedirectTargetVerifierTests.cs	Tests redirect error line annotations.
actions/docs-verifier/tests/GitHub.UnitTests/PathVerifierTests.cs	Tests external-source handling and path diagnostics.
actions/docs-verifier/src/RedirectionVerifier/RedirectTargetVerifier.cs	Adds redirect URL line tracking.
actions/docs-verifier/src/DocfxVerifier/PathVerifier.cs	Adds path line tracking and external-source filtering.

Review details

Suppressed comments (2)

actions/docs-verifier/src/DocfxVerifier/PathVerifier.cs:307

• Every missing build.content[].src is classified as an external source here, so a typo or deleted local content directory can silently exempt all fileMetadata globs beneath it from validation. Distinguish external-repository sources using the configuration contract, or continue validating paths under missing local sources before suppressing the error.

                if (resolvedPath is null || (!Directory.Exists(resolvedPath) && !File.Exists(resolvedPath)))
                {
                    result.Add(normalizedSourcePath.TrimEnd('/'));

actions/docs-verifier/src/RedirectionVerifier/RedirectTargetVerifier.cs:149

• This scan is not scoped to the redirections array, while its results are indexed against that array. An unrelated or nested redirect_url property elsewhere in the JSON can add an extra line number and make every subsequent annotation point to the wrong entry; track tokens only within each redirection object.

            if (reader.TokenType != JsonTokenType.PropertyName || !reader.ValueTextEquals("redirect_url"))
            {

• Files reviewed: 4/4 changed files
• Comments generated: 2
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

🟡 Changes recommended

Critical BOM parsing issues, a moderate case-sensitivity issue, and an indentation nit remain unresolved.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Review details

Suppressed comments (4)

actions/docs-verifier/src/DocfxVerifier/PathVerifier.cs:303

• This newly added declaration is not indented to the surrounding C# block, unlike the 4-space indentation required by actions/docs-verifier/.editorconfig:10-13, which makes the method harder to read and violates the repository's formatting convention.

string normalizedSourcePath = NormalizePath(srcPath);

actions/docs-verifier/src/DocfxVerifier/PathVerifier.cs:322

• DocFX content matching is configured as case-insensitive elsewhere (actions/docs-verifier/src/RedirectionVerifier/DocfxConfiguration.cs:36), but this external-source check uses ordinal comparisons. If an external src and its fileMetadata path differ only by case, the missing prefix is not recognized as belonging to that source and a false invalid-path error is reported. Use OrdinalIgnoreCase for both comparisons here (and keep it consistent with the source-path matching semantics).

                if (pathPrefix.Equals(sourceDirectory, StringComparison.Ordinal)
                    || pathPrefix.StartsWith(sourceDirectory + "/", StringComparison.Ordinal))

actions/docs-verifier/src/DocfxVerifier/PathVerifier.cs:235

• The line scanner matches any nested build.fileMetadata suffix, even though validation only reads the root build property. If an ignored JSON section contains a nested build.fileMetadata before the real root section, its path lines are added first and subsequent diagnostics are shifted to the wrong lines; require the expected root container depth as well.

                    if (containerPath.Count >= 3
                        && containerPath[^2] == "fileMetadata"
                        && containerPath[^3] == "build")

actions/docs-verifier/src/RedirectionVerifier/RedirectTargetVerifier.cs:163

• This scan enters the first property named redirections at any depth, not necessarily the root array that OpenPublishingRedirections deserializes. An ignored nested object such as {"metadata":{"redirections":[...]},"redirections":[...]} adds extra entries and shifts every later diagnostic to the wrong line; restrict this match to the root array depth.

                    if (!inRedirectionsArray
                        && string.Equals(currentPropertyName, "redirections", StringComparison.Ordinal))
                    {

• Files reviewed: 4/4 changed files
• Comments generated: 2
• Review effort level: Lite

[BillWagner]

This LGTM. Let's