Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[LintDiff] Need separate ruleset for TypeSpec-generated Swaggers #7732

Closed
tjprescott opened this issue Nov 6, 2023 · 2 comments
Closed

[LintDiff] Need separate ruleset for TypeSpec-generated Swaggers #7732

tjprescott opened this issue Nov 6, 2023 · 2 comments
Assignees
Labels
Central-EngSys This issue is owned by the Engineering System team. Spec PR Tools Tooling that runs in azure-rest-api-specs repo.

Comments

@tjprescott
Copy link
Member

We need the following capabilities in LintDiff:

  1. Creation of a distinct ruleset for TypeSpec-generated Swaggers, which is a subset of the normal ruleset for hand-authored Swaggers. There should never be a rule in the TypeSpec ruleset that is not in the normal ruleset. The goal will be to shrink the number of rules in this ruleset until it is empty, and no LintDiff rules run against TypeSpec-generated Swaggers.
  2. We need a flag or other parameter to tell LintDiff which ruleset to apply.

The mechanism will allow us to accomplish the following goals:

  1. Avoid a LintDiff failure when the corresponding TypeSpec rule has been purposefully suppressed. Authors should not have to suppress the same thing twice.
  2. Allows us to use LintDiff as a backstop for catching issues when an equivalent check does not exist in TypeSpec. As we add equivalent checks to TypeSpec, or identify rules that aren't relevant to TypeSpec-generated Swagger, we will remove them from this ruleset. Eventually, this ruleset will be small or empty.
@mikeharder mikeharder self-assigned this Nov 6, 2023
@tjprescott
Copy link
Member Author

tjprescott commented Nov 7, 2023

Another proposed solution would be to allow the lintdiff command to accept a list of rules to ignore. This could be simpler to implement.

cc/ @allenjzhang

@konrad-jamrozik
Copy link
Contributor

konrad-jamrozik commented Feb 27, 2024

This work is now completed.

Test PR:
https://github.com/Azure/azure-rest-api-specs/pull/27936/checks?check_run_id=22018004440

Log:
https://dev.azure.com/azure-sdk/internal/_build/results?buildId=3532098&view=logs&j=0574a2a6-2d0a-5ec6-40e4-4c6e2f70bea2&t=80c3e782-49f0-5d1c-70dd-cbee57bdd0c7

Raw log:
https://dev.azure.com/azure-sdk/590cfd2a-581c-4dcb-a12e-6568ce786175/_apis/build/builds/3532098/logs/286

The raw log shows rules have been disabled for TypeSpec-generated specs:

	Line 210: 2024-02-27T07:19:53.6176794Z {"pluginName":"spectral","extensionName":"@microsoft.azure/openapi-validator","level":"information","message":"DISABLED Spectral rule for TypeSpec-generated OpenAPI specs, severity 'DISABLED': 'AdditionalPropertiesAndProperties'"}
	Line 242: 2024-02-27T07:19:53.6196764Z {"pluginName":"spectral","extensionName":"@microsoft.azure/openapi-validator","level":"information","message":"DISABLED Spectral rule for TypeSpec-generated OpenAPI specs, severity 'DISABLED': 'Nullable'"}
	Line 247: 2024-02-27T07:19:53.6201570Z {"pluginName":"spectral","extensionName":"@microsoft.azure/openapi-validator","level":"information","message":"DISABLED Spectral rule for TypeSpec-generated OpenAPI specs, severity 'DISABLED': 'OperationSummaryOrDescription'"}
	Line 251: 2024-02-27T07:19:53.6204248Z {"pluginName":"spectral","extensionName":"@microsoft.azure/openapi-validator","level":"information","message":"DISABLED Spectral rule for TypeSpec-generated OpenAPI specs, severity 'DISABLED': 'ParameterDescription'"}
	Line 262: 2024-02-27T07:19:53.6211148Z {"pluginName":"spectral","extensionName":"@microsoft.azure/openapi-validator","level":"information","message":"DISABLED Spectral rule for TypeSpec-generated OpenAPI specs, severity 'DISABLED': 'PropertyDescription'"}
	Line 270: 2024-02-27T07:19:53.6216280Z {"pluginName":"spectral","extensionName":"@microsoft.azure/openapi-validator","level":"information","message":"DISABLED Spectral rule for TypeSpec-generated OpenAPI specs, severity 'DISABLED': 'SchemaDescriptionOrTitle'"}
	Line 271: 2024-02-27T07:19:53.6216932Z {"pluginName":"spectral","extensionName":"@microsoft.azure/openapi-validator","level":"information","message":"DISABLED Spectral rule for TypeSpec-generated OpenAPI specs, severity 'DISABLED': 'SchemaNamesConvention'"}

but not for manually-written specs, e.g.:

2024-02-27T07:19:53.6160999Z {"pluginName":"spectral","extensionName":"@microsoft.azure/openapi-validator","level":"information","message":"Spectral rule for manually written OpenAPI specs, severity 'Warning': 'PropertyDescription'"}

We can also see the spec was recognized as TypeSpec-generated (TypeSpec-generated: true):

2024-02-27T07:19:53.6226341Z {"pluginName":"spectral","extensionName":"@microsoft.azure/openapi-validator","level":"information","message":"spectralPluginFunc: Validating OpenAPI spec. TypeSpec-generated: true. Path: 'file:///mnt/vss/_work/1/azure-rest-api-specs/specification/contosowidgetmanager/data-plane/Azure.Contoso.WidgetManager/preview/2022-11-01-preview/widgets.json'"}

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Central-EngSys This issue is owned by the Engineering System team. Spec PR Tools Tooling that runs in azure-rest-api-specs repo.
Projects
Archived in project
Status: 🎊 Closed
Development

Successfully merging a pull request may close this issue.

3 participants