@quobix/vacuum 0.33.2 → 0.35.1

package/README.md

@@ -87,7 +87,7 @@ To do that, replace `dshanley/vacuum` with `ghcr.io/daveshanley/vacuum` in the a
 
 ## Run with Go
 
-If you have Go 1.26 or newer installed, you can use `go run` to build and run it:
+If you have Go 1.27.3 or newer installed, you can use `go run` to build and run it:
 
 ```
 go run github.com/daveshanley/vacuum@latest lint <your-openapi-spec.yaml>
@@ -153,7 +153,22 @@ A timeout is an incomplete check, not evidence that the document is clean.
 
 ## Documentation
 
-🔥 **New in** `v0.33` 🔥: **Arazzo workflow linting and a new `or` function**
+🔥 **New in** `v0.34` 🔥: **Agent testing in vacuum**
+
+A new `test` command gives agents a way to test rules, check changes and verify repairs using vacuum's existing engine.
+Define a YAML or JSON suite, run `vacuum test suite.yaml`, and get structured results with evidence of what each rule actually did.
+
+Check expected findings, selector matches and function calls. Test before-and-after changes, verify autofix output,
+and check that running a fix again makes no further change. A clean result is only useful if the rule actually ran.
+
+- [Get started with agent testing](https://quobix.com/vacuum/agent-testing/)
+- [Read the `test` command reference](https://quobix.com/vacuum/commands/test/)
+- [Read more about execution evidence](https://quobix.com/vacuum/testing/evidence/)
+- [Use the test harness from Go](https://quobix.com/vacuum/api/test-harness/)
+
+---
+
+`v0.33`: **Arazzo workflow linting and a new `or` function**
 
 Arazzo 1.0 and 1.1 workflows are now a first-class document type in vacuum, alongside OpenAPI, AsyncAPI and JSON Schema.
 Use `vacuum lint workflows.yaml` and vacuum will detect Arazzo automatically, with recommended rules for workflow structure,
@@ -268,17 +283,34 @@ vacuum apply-overlay internal.yaml public.overlay.yaml public.yaml \
   --prune-unused
 ```
 
-Inclusive tags are exact and case-sensitive; `any` keeps operations with at
-least one included tag and `all` requires every included tag. Untagged
-operations are removed. Filtering runs after Overlay actions and before
-reachability-based component pruning. These opt-in transforms require a
-bundled, self-contained OpenAPI document. Top-level Tag Objects are retained.
-YAML aliases and merge keys are expanded when filtering. Retained mapping
+The overlay file is optional when a filter or `--prune-unused` is active:
+
+```bash
+vacuum apply-overlay internal.yaml public.json --exclude-tag internal --prune-unused
+vacuum apply-overlay internal.yaml selected.yaml --include-operation-id listPets
+```
+
+Tags and operation IDs are exact and case-sensitive. All four filter flags
+(`--include-tag`, `--exclude-tag`, `--include-operation-id`, and
+`--exclude-operation-id`) can be repeated. `--tag-match any` matches at least
+one tag; `all` requires every tag in each include/exclude list. Each active
+inclusion filter must match, and exclusions take precedence. Operations with
+no tags or IDs survive exclusion-only filtering. Filtering runs after Overlay
+actions and before pruning. `--prune-unused` removes unreachable components
+and unused tag definitions, retaining parents of used OpenAPI 3.2 tags.
+These opt-in transforms require a bundled, self-contained OpenAPI document.
+YAML merge keys are expanded. Aliases are expanded when filtering or when a removed tag owns an anchor. Retained mapping
 order, comments, and scalar styles are preserved. Pruning rejects schema
 `$id` scopes that cannot be resolved safely. Link Objects targeting filtered
 operations are retained and reported as warnings. Document output remains
 pure on stdout; warnings are written to stderr. The warning summary uses the `apply-overlay produced` prefix to
 cover both Overlay actions and publication transforms.
+A `.json`, `.yaml`, or `.yml` output extension selects the output format.
+Otherwise the input format is retained, including on stdout.
+An inferred output path containing an Overlay document is rejected to prevent accidental overwrites.
+Tag pruning retains `x-tagGroups` entries and `x-traitTag: true` narrative tags.
+Library callers opt into tag pruning with `Options.PruneUnusedTags`;
+`Options.PruneUnused` and `PruneUnusedComponents` continue to prune components only.
 
 ---
 
@@ -536,9 +568,26 @@ recognizes a compressed report file and will deal with it automatically when rea
 
 > When using compression, the file name will be `vacuum-report-MM-DD-YY-HH_MM_SS.json.gz`. vacuum uses gzip internally.
 
+## Selecting property names in custom rules
+
+Use quoted bracket notation for JSONPath property names with special characters, for example `['$ref']` and `['application/json']`. vacuum does not support JSONPath-Plus backtick escapes.
+
+To inspect a `$ref` property itself, set `resolved: false`. With `resolved: true`, rules inspect the referenced schema after resolution.
+
+```yaml
+rules:
+  no-request-body-refs:
+    description: Request body schemas must be inline.
+    given: "$.paths.*.*.requestBody.content['application/json'].schema['$ref']"
+    resolved: false
+    severity: warn
+    then:
+      function: falsy
+```
+
 ## Ignoring specific linting errors
 
-You can ignore specific linting errors by providing an `--ignore-file` argument to commands that run or replay lint results, including `lint`, `report`, `spectral-report`, `html-report`, `dashboard`, and `docs`.
+You can ignore specific linting errors by providing an `--ignore-file` argument to commands that run or replay lint results, including `lint`, `report`, `spectral-report`, `html-report`, `dashboard`, `docs`, `schema`, and `language-server`.
 
 ```
 ./vacuum lint --ignore-file <path-to-ignore-file.yaml> -d <your-openapi-spec.yaml>
@@ -548,6 +597,16 @@ You can ignore specific linting errors by providing an `--ignore-file` argument
 ./vacuum report --ignore-file <path-to-ignore-file.yaml> -c <your-openapi-spec.yaml> <report-prefix>
 ```
 
+Repeat `--ignore-file` to combine waivers from multiple files. Paths for the same rule are appended; an unreadable or invalid file stops the command.
+
+```sh
+./vacuum lint --ignore-file pets-ignore.yaml --ignore-file stores-ignore.yaml api.yaml
+```
+
+In `vacuum.conf.yaml`, `ignore-file` accepts either one path or a YAML list of paths. A scalar value, including `VACUUM_IGNORE_FILE`, is always one path; commas are part of the filename.
+
+Language-server editor settings accept `ignoreFiles: ["one.yaml", "two.yaml"]`; the legacy `ignoreFile` string still works. An empty `ignoreFiles` list clears waivers. Explicit CLI ignore files override disk config; editor initialization and workspace settings can override the CLI defaults.
+
 The ignore-file should point to a `.yaml` file that contains exact result paths or JSONPath expressions to be ignored by vacuum. The structure of the YAML file is as follows:
 
 ```
@@ -602,7 +661,7 @@ for scoped exceptions.
 
 ## Spectral migration
 
-vacuum loads YAML and JSON rulesets. Resolve each relative `extends` path from the
+vacuum loads YAML, JSON, and local JavaScript rulesets. Resolve each relative `extends` path from the
 file that contains it, including on Windows. Keep sibling rulesets relative:
 
 ```yaml
@@ -614,8 +673,17 @@ extends:
 
 Use `[vacuum:owasp, all]` for vacuum's built-in OWASP checks instead of importing
 `@stoplight/spectral-owasp-ruleset/dist/ruleset.mjs`. The native rules use vacuum's
-rule names and behavior; they do not execute the Spectral package. JavaScript
-ruleset modules (`.js`, `.mjs`, `.cjs`) are not supported.
+rule names and behavior; they do not execute the Spectral package.
+
+For JavaScript rulesets, export an object from a local `.js`, `.mjs`, or `.cjs` file:
+
+```shell
+vacuum lint api.yaml -r rules.mjs
+```
+
+Functions, static imports, Promises, and callable formats run in an isolated runtime
+for each document. See [JavaScript rulesets](https://quobix.com/vacuum/rulesets/javascript/)
+for supported imports, context, and migration limits.
 
 Arazzo 1.0 and 1.1 workflows use `vacuum lint workflows.yaml` and the normal
 report commands. `spectral:arazzo` selects Vacuum's native recommended rules.
@@ -628,7 +696,7 @@ and migration differences.
 vacuum lint api.yaml --ruleset rules/main.yaml --functions ./functions
 ```
 
-It does not enable JavaScript ruleset modules. Omitting the directory reports an
+JavaScript ruleset functions do not need this directory. Omitting the directory after `--functions` reports an
 input error and exits with code 2. In the editor, vacuum checks recognized ruleset
 buffers against its ruleset schema instead of reporting an unsupported API type.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quobix/vacuum",
-  "version": "0.33.2",
+  "version": "0.35.1",
   "description": "The world's fastest, most scalable and complete OpenAPI parser",
   "type": "module",
   "author": "Dave Shanley",
@@ -23,11 +23,11 @@
     "npm-install"
   ],
   "dependencies": {
-    "https-proxy-agent": "^9.0.0",
-    "tar": "^7.5.21"
+    "https-proxy-agent": "^9.1.0",
+    "tar": "^7.5.22"
   },
   "devDependencies": {
-    "@sourcemeta/jsonschema": "^15.6.3"
+    "@sourcemeta/jsonschema": "^17.2.1"
   },
   "bugs": {
     "url": "https://github.com/daveshanley/vacuum/issues"