Azure / Azure/avocado

[MISSING_APIS_IN_DEFAULT_TAG] False positive if readme.md uses windows paths instead of posix paths

Open
#167 0 comments 0 reactions 1 assignee Claimed by @mikeharder View on GitHub
Dominant language
TypeScript
Stars
23
Forks
22
Avg merge
2d 9h
Merged PRs (30d)
13

Description

https://github.com/Azure/azure-rest-api-specs-pr/blob/34c96e47be718063d4e2de4412cc4b1ee9f7d149/specification/monitor/resource-manager/Microsoft.Monitor/PipelineGroups/readme.md?plain=1

This readme incorrect used windows paths (backslash) instead of posix paths (forward-slash).

Expected:

```
input-file:
- preview/2024-10-01-preview/pipelineGroups.json
```

Actual:

```
input-file:
- preview\2024-10-01-preview\pipelineGroups.json
```

Strangely, most of Avocado worked correctly, but it caused false positives in rule `MISSING_APIS_IN_DEFAULT_TAG`.

Workaround is to use posix paths in readme.

Fix is either:

1. Fail fast if readme contains windows paths
2. Ensure paths are normalized before comparisons
* Most Avocado rules seemed to work correctly, so maybe bug is specific to `MISSING_APIS_IN_DEFAULT_TAG`.

## Root Cause
I believe the root cause is in dep `@azure/openapi-markdown`. This returns the input-file "strings", but doesn't attempt to resolve or normalize them:

https://github.com/Azure/openapi-markdown/blob/58d65b9ccc1effd3d206a171e6d893cf3b9074b0/src/readMeManipulator.ts#L167-L168

We might be able to fix/workaround in Avocado, by either normalize (or validating) paths after calling this API:

https://github.com/Azure/avocado/blob/0576dad051bd785e7ca71de1a1d4fb676abc9ae5/src/index.ts#L209-L216

https://github.com/Azure/avocado/blob/0576dad051bd785e7ca71de1a1d4fb676abc9ae5/src/index.ts#L392-L402

Another question, if a file doesn't exist, would it be better for Avocado to throw immediately, rather than silently using an empty map?

https://github.com/Azure/avocado/blob/0576dad051bd785e7ca71de1a1d4fb676abc9ae5/src/index.ts#L491-L494

Our new code in spec-model attempts to normalize and resolve, so it should always return platform-specific absolute paths. Though even this code might be sub-optimal or have bugs.

https://github.com/Azure/azure-rest-api-specs/blob/63ea5930957bc33f38a9f1071c7c41a07eea80d4/.github/shared/src/readme.js#L156-L158

https://github.com/Azure/azure-rest-api-specs/blob/63ea5930957bc33f38a9f1071c7c41a07eea80d4/.github/shared/src/readme.js#L78-L85

Contributor guide

No contributing guide indexed for this repository

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.