feature: add support for auto fixing rule violations

[tx3stn]

👋 me again.

One thing I'd like to use for some of my custom rules is the ability to auto fix simple things with a --fix flag, so this PR adds that.

Note

This doesn't add any fixes for any built-ins so needs to be added in the same way you would custom functions, so I've tried to stick to the same sort of approach as used there.

Approach

1. Add a new AutoFixFunction to the rule struct (so you can define autoFixFunction on your custom rules)

type AutoFixFunction func(node *yaml.Node, document *yaml.Node, context *RuleFunctionContext) (*yaml.Node, error)

The auto fix functions takes in the yaml node with the error, the whole document (which enables you to refer to other parts of the document, which I anticipate being useful for something like adding examples using schema components defined in the file), and the rule context.

2. Add a map of auto fix functions in the same way the map of custom functions is added.
3. When the results are are processed, if an auto fix function is set on the rule that is flagged try and run the auto fix function.
4. If the auto fix function errors, log the error, add the failing rule to the results so it still gets reported.
5. If the auto fix function succeeds, replace the yaml node with the transformed fixed version.
6. When results are all done, if the fix flag is applied create a back up of the existing file in /tmp directory, then overwrite the file in place with the fixed version.

Example in use

Warning

Tested it out where I'm using vacuum as library inside another tool, so note the output here is a custom output, but the processing of results and auto fixing is all done by vacuum, I'm just displaying the results in a custom manner.

Screen.Recording.2025-10-31.at.14.39.40.mov

The lint is flagging a custom rule not use enum fields, and then the fix is replacing the enum with x-extensible-enum as per our requirements.

Additional improvements

I've not covered off all the functionality in this to prevent it from getting too big, so once this is merged I'll add functionality for:

1. Applying an autofix in the TUI dashboard.
2. Applying an autofix via a code action when running in LSP.

simple spec used in screen recording.

openapi: 3.0.3
info:
    title: Prefer compatible extensions test
    description: Test specification for compatible extensions
    contact:
        name: API Support
        email: [email protected]
    x-audience: internal-team
    x-domain-gateway-integration:
        serviceName: test-service
        lambda: arn:aws:lambda:us-east-1:123456789012:function:test-function
servers:
    - url: https://api.test.com/v1
      description: Production server
tags:
    - name: test
      description: Test operations
components:
    schemas:
        ValidSchema:
            title: ValidSchema
            description: A valid schema using x-extensible-enum
            type: string
            x-extensible-enum:
                - VALUE_ONE
                - VALUE_TWO
        InvalidSchema:
            title: InvalidSchema
            description: A schema that uses enum instead of x-extensible-enum
            type: string
            enum:
                - VALUE_ONE
                - VALUE_TWO
paths:
    /test:
        get:
            operationId: listTest
            tags:
                - test
            summary: Test endpoint
            description: Test endpoint that uses the schemas
            responses:
                '200':
                    description: Success
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: '#/components/schemas/ValidSchema'
                                    - $ref: '#/components/schemas/InvalidSchema'
                            example: VALUE_ONE
                '400':
                    description: Bad request
                '500':
                    description: Internal server error
                default:
                    description: Unexpected error

[daveshanley]

OK, So first of all, this is great. Thank you so much for building this. I've been thinking about this for about a year and a half and never had the time to get around to it, and you've gone ahead and built it in the exact same way that I wanted it built. It's like you read my mind. Thank you.

My only request is that because this is such a fundamental feature, It's a new building block for how we make this tool completely customizable and extensible. we need some documentation. I can actually add the detailed documentation, but I'm going to need something to work from. Can you write something into the README at the bottom talking about this new capability?

I love to see the custom UI with vacuum powering it in the background. That's exactly what I built this tool for, for people to make it their own. It makes me really happy to see somebody making it their own.

[tx3stn]

I've rebased, squashed the commits so it's a bit cleaner, added a --fix-file flag which will write the updates to a new file, updated the "what's new in version...." section like I did for the x-lint-ignore release, and added some docs about usage to the README.

Let me know if it all makes sense!

I love to see the custom UI with vacuum powering it in the background. That's exactly what I built this tool for, for people to make it their own. It makes me really happy to see somebody making it their own.

And just to say thanks for building this in the first place, it's been amazing to just wrap our own config around vacuum as a library and give teams amazing tooling to work with and that's all because we've just built on top of what vacuum offers out of the box!