@quobix/vacuum 0.33.1 → 0.35.0

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>
@@ -137,9 +137,38 @@ like our _very kind_ sponsors, past and present:
 Need help? Have a question? Want to share your work? [Join our discord](https://discord.gg/UAcUF78MQN) and
 come say hi!
 
+## Timeout behavior
+
+Resolved rule lookups no longer retry against unresolved documents after a timeout or query error.
+This applies to plain linting and dashboard commands, reports, and library callers as well as `--original` comparisons.
+`lint` and `dashboard` return exit code 2 when a lookup or rule execution times out.
+Without `--original`, `vacuum report` records these failures as execution errors; its findings can be incomplete.
+Spectral and HTML output retain their existing formats and can omit findings from failed rules.
+A comparison with `--original` stops with exit code 2 if either lint run fails and does not produce a comparison report.
+Library callers must check `RuleSetExecutionResult.Errors`, including `RuleLookupError` and `RuleTimeoutError`.
+
+For large documents, increase `--lookup-timeout` (milliseconds, default 500) if a JSONPath lookup needs more time,
+or `--timeout` (seconds, default 5) if the complete rule needs more time. The rule budget must also allow the lookup to finish.
+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,
@@ -254,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.
 
 ---
 
@@ -588,7 +634,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
@@ -600,8 +646,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.
@@ -614,7 +669,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.1",
+  "version": "0.35.0",
   "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"