Unresolved references not throwing an error in v2

[crudbee]

Describe the bug
One of our integration tests seem to have flagged a regression from v1 to v2. This seems to have been tackled a couple of times, first in #1470, resolved by #1503. It then looks like Warnings were noticed to be gone and added back by #2459.

The test from #1503 still passes, but it looks like the errors is not added if the reference lives in the path (I didn't dig deeper yet).

OpenApi File To Reproduce

openapi: 3.0.3
info:
  title: UserAPI
  version: '1.0'
  description: The User API
servers:
  - url: 'http://localhost:3000'
paths:
  '/v1/users/{userId}':
    parameters:
      - $ref: '#/components/parameters/userId'
    get:
      summary: Get User Info by User ID
      tags:
        - users
      responses:
        '200':
          description: User Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/user'
      description: Retrieve the information of the user with the matching user ID.
components:
  schemas:
    User:
      title: User
      type: object
      description: ''
      properties:
        id:
          type: integer
          description: Unique identifier for the given user.
        firstName:
          type: string
        lastName:
          type: string
      required:
        - id
        - firstName
        - lastName
  parameters:
    userId:
      name: userId
      in: path
      required: true
      schema:
        type: string
      description: the id of an existing user
tags:
  - name: users

Expected behavior
Since #1503 has an explicit test case containing the error I am looking for, I am assuming it is intended for there to be a "Invalid reference" error with the above file, rather than just a warning.

Screenshots/Code Snippets
Example test snippet for v1 (passes)

[Fact]
public async Task Validate_ThrowsReferenceDoesntExist_Error()
{
    // Arrange
    var input = 
    """
[...snip, use the above example...]
    """;
    var reader = new OpenApiStreamReader();
    await using var stream = new MemoryStream(Encoding.UTF8.GetBytes(input));

    // Act
    var result = await reader.ReadAsync(stream);

    // Assert
    (result.OpenApiDiagnostic != null && result.OpenApiDiagnostic.Errors.Any()).Should().BeTrue();
    result.OpenApiDiagnostic.Errors.Should().BeEquivalentTo(new List<OpenApiError>
    {
        new(new OpenApiException("Invalid Reference identifier 'user'."))
    });
}

The v2 equivalent:

[Fact]
public async Task Validate_ThrowsReferenceDoesntExist_Error()
{
    // Arrange
    var input =
    """
[...snip, use the above example...]
    """;
    var settings = new OpenApiReaderSettings();
    settings.AddYamlReader();
    await using var stream = new MemoryStream(Encoding.UTF8.GetBytes(input));

    // Act
    var result = await OpenApiDocument.LoadAsync(stream, null, settings, CancellationToken.None);

    // Assert
    (result.Diagnostic != null && result.Diagnostic.Errors.Any()).Should().BeTrue();
    result.Diagnostic.Errors.Should().BeEquivalentTo(new List<OpenApiError>
    {
        new(new OpenApiException("Invalid Reference identifier 'user'."))
    });
}

result.Diagnostic.Errors is empty, though the warning about the non-existent reference is there.

[crudbee]

The test expectation in test/Microsoft.OpenApi.Readers.Tests/OpenApiReaderTests/OpenApiDiagnosticTests.cs#DiagnosticReportMergedForExternalReferenceAsync was removed in #1955, and I must admit, I don't think I immediately see why. Is the lack of error actually intentional?

e: Nope, got it, the previously tested for error was about empty paths, my bug is specifically about what seems to be a change of behaviour on a slightly different setup.

[baywet]

Hey everyone!
Thank you for using the SDK and for reaching out.
Thank you for your patience.

Somehow I had missed this issue...
This is by design because of the revamp of how references work, lazy loading, the workspace system, etc...

However, there was clearly a documentation gap on this aspect, so I put together #2692

In addition, I updated hidi to log warnings as well during validation, #2691

Let me know if you have any additional comments or questions.