@quobix/vacuum 0.19.5 → 0.20.1

package/README.md

@@ -144,7 +144,17 @@ come say hi!
 
 ## Documentation
 
-🔥 **New in** `v0.19` 🔥: **Ignore rules with `x-lint-ignore`**
+🔥 **New in** `v0.20` 🔥: **Support for auto fixing custom rules**
+
+Got some rules that don't really need a human to look at?
+
+Well now you can define an `AutoFixFunction` for your rules, and when you run with the `--fix` flag, the fixes will will be applied to the file, or use `--fix-file` to write them to a different file.
+
+See [Auto-Fixing Rule Violations](#auto-fixing-rule-violations) for more specifics.
+
+---
+
+`v0.19`: **Ignore rules with `x-lint-ignore`**
 
 Got an error in your spec you know about but can't get round to fixing yet?
 Migrating from zally and wanting to keep your existing `x-zally-ignore` issues silenced?
@@ -171,8 +181,6 @@ New rules:
 
 ---
 
-
-
 `v0.17`: **Github Action**.
 
 vacuum now has an official Github Action. [Read the docs](https://quobix.com/vacuum/github-action/), or check it out
@@ -203,116 +211,7 @@ $refs being used in path items.
 
 ---
 
-`v0.14+`: **Engine Speedup**.
-
-**Speed!** We've made some significant improvements to how efficiently large documents are walked
-Which means vacuum is now faster than ever.
-
----
-
-`v0.12+` : Core functions support JSON Path.
-
-Now all **core** functions return the **correct and accurate JSON path for each linting result**. Previously this was not possible
-at all, but with some clever engineering, we have made it happen. It's a small thing, but with huge impact.
-
-This feature has been available on the OpenAPI functions for some time, however core functions were without a comparison.
-But no more! core functions have joined the party.
-
-A new `--no-clip` flag is available on the `lint` command. This prevents message/path truncation.
-
----
-
-`v0.11+`: Ignore Linting Errors/Violations.
-
-v0.11 introduces the ability to ignore specific linting errors. This is useful for when you want to implement new 
-rules to existing production APIs. In some cases, correcting the lint errors would result in a breaking change. 
-
-Having a way to ignore these errors allows you to implement the new rules for new APIs while maintaining 
-backwards compatibility for existing ones.
-
-[Learn more about ignoring violations](https://quobix.com/vacuum/ignoring/)
-
----
-
-`v0.10+` : **Quality release**.
-
-v0.10 is a quality release, with a number of fixes and improvements to rule schemas, function names and more. 
-vacuum now powers [The OpenAPI doctor](https://pb33f.io/doctor/). To enable correct ruleset management and automation
-a number of functions have been renamed, interfaces have been upgraded and rule functions schemas are now accurate. 
-
-This is a breaking change for anyone using vacuum as a library with custom rules. 
-
----
-
-`v0.9+` : **Built in Language Server**.
-
-A new command is available `language-server`. This starts vacuum as an LSP compatible language server. Run vacuum
-in your favorite IDE and get linting and validation as you type, in realtime.
-
-Will support any LSP compatible editor, like VSCode, Sublime, vim, etc.
-
-[Install the VSCode extension](https://marketplace.visualstudio.com/items?itemName=pb33f.vacuum)
-[Learn more about the language-server command](https://quobix.com/vacuum/commands/language-server/)
-
----
-
-`v0.8+` : **OpenAPI Bundler**.
-
-A new command is available `bundle` will bundle all external references for an OpenAPI file into a single file.
-
-[Learn more about the bundle command](https://quobix.com/vacuum/commands/bundle/)
-
-A new linting rule is available `oas-schema-check` will perform type checks and validation on all schemas in your
-OpenAPI file. It's enabled by default in the recommended ruleset.
-
-[oas-schema-check rule docs](https://quobix.com/vacuum/rules/schemas/oas-schema-check/)
-
----
-
-`v0.7+` : **Hard Mode**.
-
-Want to lint your spec with the most strict ruleset possible? Now you can! Use the `-z` / `--hard-mode` flag to enable
-
----
-
-`v0.6+` : **Sharable / distributed rulesets**  now available.
-
-Want to share / extend / distribute your own rulesets? Now you can!
 
-[Learn more about sharable rulesets](https://quobix.com/vacuum/rulesets/sharing/)
-
----
-
-`v0.5+` : **Multi-file linting**  now available for the `lint` command.
-
-Want to lint multiple files at once? Now you can!
-
-```shell
-vacuum lint file1.json path/to/file2.yaml file3.json 
-```
-
-Want to suck in a ton of files? Use a **glob** pattern!
-
-```shell
-vacuum lint some/path/**/*.yaml 
-```
-
-
----
-`v0.3+`: [Custom JavaScript Functions](https://quobix.com/vacuum/api/custom-javascript-functions/) are now available out of the box.
-
-Write custom functions in JavaScript and use them in any ruleset. No need
-to compile golang code to extend vacuum anymore!
-
-[Learn more about building custom JavaScript functions](https://quobix.com/vacuum/api/custom-javascript-functions/).
-
-
----
-`v0.2+`: [OWASP API rules](https://quobix.com/vacuum/rules/owasp/) are now available out of the box.
-
-[Learn more about enabling OWASP API rules](https://quobix.com/vacuum/rulesets/owasp/).
-
----
 
 ### [Quick Start Guide 🚀](https://quobix.com/vacuum/start)
 
@@ -365,7 +264,7 @@ See all the documentation at https://quobix.com/vacuum
 Designed to reliably lint OpenAPI specifications, **very, very quickly**. Including _very large_ ones. Spectral can be quite slow
 when used as an API and does not scale for enterprise applications.
 
-vacuum will tell you what is wrong with your spec, why, where and how to fix it. 
+vacuum will tell you what is wrong with your spec, why, where, and how to fix it. 
 
 vacuum will work at scale and is designed as a CLI (with a web or console UI) and a library to be consumed in other applications.
 
@@ -616,4 +515,109 @@ You can configure global vacuum flags using environmental variables in the form
 
 If a flag, has a `-` in it, replace with `_`
 
+
+## Auto-fixing rule violations
+
+If you have a rule that doesn't need a human to look at it, and the change can be reliably automated you can configure an `AutoFixFunction` on the rule. When you then run the `lint` command you can pass the `--fix` flag and the violation will be automatically fixed.
+
+### Set up
+
+1. Define a rule that has an `autoFixFunction`, e.g.:
+```yaml
+rules:
+  use-compatible-extensions:
+    autoFixFunction: useExtensibleEnum
+    description: Prefer compatible extensions
+    id: use-compatible-extensions
+    given: "$.components.schemas[?@.enum]"
+    severity: warn
+    message: Use x-extensible-enum instead of enum for better compatibility
+    then:
+      field: enum
+      function: falsy
+```
+
+This rule flags any usage of `enum` and recommends they are updated to `x-extensible-enum`.
+A simple change which can be easily auto fixed!
+
+2. Create a function which performs the auto-fix.
+```go
+func useExtensibleEnum(
+	node *yaml.Node,
+	document *yaml.Node,
+	context *model.RuleFunctionContext,
+) (*yaml.Node, error) {
+	if node.Kind != yaml.MappingNode {
+		return node, nil
+	}
+
+	for i := 0; i < len(node.Content); i += 2 {
+		if i+1 >= len(node.Content) {
+			break
+		}
+
+		keyNode := node.Content[i]
+
+		if keyNode.Value == "enum" {
+			keyNode.Value = "x-extensible-enum"
+
+			return node, nil
+		}
+	}
+
+	return node, nil
+}
+```
+
+> [!NOTE]
+> The auto fix function must satisfy the `AutoFixFunction` type.
+> It should take in the `*yaml.Node` of the violation, the root `*yaml.Node` of the document and the `RuleFunctionContext`.
+> It should return the fixed `*yaml.Node` and an error.
+
+3. Configure your `RuleSetExecution` to use the auto fix function.
+```go
+func Lint(rulesFile string, specFile string) error {
+	rules, err := rulesets.LoadLocalRuleSet(ctx, rulesFile)
+	if err != nil {
+		return fmt.Errorf("error loading ruleset: %w", err)
+	}
+
+	rs := rulesets.BuildDefaultRuleSetsWithLogger(slog.Logger).
+		GenerateRuleSetFromSuppliedRuleSet(rules)
+
+	// NOTE: only showing the fields on the RuleSetExecution relevant to auto-fixing.
+	results := motor.ApplyRulesToRuleSet(&motor.RuleSetExecution{
+		AutoFixFunctions: map[string]model.AutoFixFunction{
+			"useExtensibleEnum": useExtensibleEnum,
+		},
+		ApplyAutoFixes:         true,
+		RuleSet:                rs,
+	})
+
+	// Write back to file if fixes were applied
+	if len(lintResults.FixedResults) > 0 && autoFix {
+		fileInfo, _ := os.Stat(specFile)
+
+		err = os.WriteFile(specFile, result.ModifiedSpec, fileInfo.Mode())
+		if err != nil {
+			return fmt.Errorf("failed to write file %s: %w", c.file, err)
+		}
+	}
+
+	return nil
+}
+```
+
+When the auto fix function runs, if it returns an error the fix will not be applied, the error will be logged, and the violation will be reported in the standard results.
+
+If the auto fix function succeeds the yaml node flagged by the violation will be replaced with the transformed version returned by the auto fix function.
+
+> [!TIP]
+> When using `vacuum` as a library You can access the fixed yaml content in the `RuleSetExecutionResult.ModifiedSpec`, and choose where to write the file.
+> 
+> When using `vacuum` as a cli, the `--fix` flag will overwrite the spec file in place, and `--fix-file` flag lets you specify an alternative file to write the content to, if you want to compare the outputs.
+
+### Usage
+
+
 > Logo gopher is modified, originally from [egonelbre](https://github.com/egonelbre/gophers)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quobix/vacuum",
-  "version": "0.19.5",
+  "version": "0.20.1",
   "description": "The world's fastest, most scalable and complete OpenAPI parser",
   "type": "module",
   "author": "Dave Shanley",