@quobix/vacuum 0.27.0 → 0.27.2

package/README.md

@@ -1,11 +1,11 @@
 ![logo](logo.png)
 
-# vacuum - The world's fastest OpenAPI & Swagger linter.
+# vacuum - The world's fastest OpenAPI and JSON Schema linter.
 
 ![build](https://github.com/daveshanley/vacuum/workflows/Build/badge.svg)
 [![Go Report Card](https://goreportcard.com/badge/github.com/daveshanley/vacuum)](https://goreportcard.com/report/github.com/daveshanley/vacuum)
 [![discord](https://img.shields.io/discord/923258363540815912)](https://discord.gg/UAcUF78MQN)
-[![Docs](https://img.shields.io/badge/godoc-reference-5fafd7)](https:/-/pkg.go.dev/github.com/daveshanley/vacuum)
+[![Docs](https://img.shields.io/badge/godoc-reference-5fafd7)](https://pkg.go.dev/github.com/daveshanley/vacuum)
 [![npm](https://img.shields.io/npm/dm/@quobix/vacuum?style=flat-square&label=npm%20downloads)](https://www.npmjs.com/package/@quobix/vacuum)
 [![Docker Pulls](https://img.shields.io/docker/pulls/dshanley/vacuum?style=flat-square)](https://hub.docker.com/r/dshanley/vacuum)
 [![Mentioned in Awesome Go](https://awesome.re/mentioned-badge-flat.svg)](https://github.com/avelino/awesome-go)
@@ -79,21 +79,32 @@ To run, mount the current working dir to the container and use a relative path t
 docker run --rm -v $PWD:/work:ro dshanley/vacuum lint <your-openapi-spec.yaml>
 ```
 Alternatively, you can pull it from
-[Github packages](https://github.com/daveshanley/vacuum/pkgs/container/vacuum).
+[GitHub packages](https://github.com/daveshanley/vacuum/pkgs/container/vacuum).
 To do that, replace `dshanley/vacuum` with `ghcr.io/daveshanley/vacuum` in the above commands.
 
 ## Run with Go
 
-If you have go >= 1.16 installed, you can use `go run` to build and run it:
+If you have Go 1.25 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>
 ```
 
+## Upgrade vacuum
+
+If vacuum was installed with Homebrew, npm, or the shell installer, run:
+
+```bash
+vacuum upgrade
+```
+
+vacuum will detect the install path and use the matching upgrade mechanism when it can. Normal commands may also show an
+update notice when a newer stable release is available. Use `--no-update-check` to skip that check for a single run.
+
 ---
 
 ## Sponsors
-If your company is using `vacuum`, please considering [supporting this project](https://github.com/sponsors/daveshanley),
+If your company is using `vacuum`, please consider [supporting this project](https://github.com/sponsors/daveshanley),
 like our _very kind_ sponsors, past and present:
 
 
@@ -133,7 +144,13 @@ generating documentation with built-in linting results is available _right insid
 Try it out! instead of the `lint` command try the `docs` command instead.
 
 - [Read more about API Docs in vacuum](https://quobix.com/vacuum/api-docs/)
+- [Read the `docs` command reference](https://quobix.com/vacuum/commands/docs/)
 - [Read more about the printing press](https://pb33f.io/printing-press/)
+- [Learn about rendering modes](https://pb33f.io/printing-press/rendering-modes/)
+- [Learn about diagnostics mode](https://pb33f.io/printing-press/diagnostics-mode/)
+- [Learn about API catalogs](https://pb33f.io/printing-press/api-catalog/)
+- [Learn about agentic AI output](https://pb33f.io/printing-press/agentic-ai/)
+- [Learn about generated outputs](https://pb33f.io/printing-press/outputs/)
 
 ---
 
@@ -175,7 +192,7 @@ Ever needed to tweak an OpenAPI spec for different environments without maintain
 Maybe swap out server URLs between dev, staging, and production? Or perhaps strip out internal endpoints before publishing the API docs?
 
 OpenAPI Overlays are the answer. They let us make non-destructive modifications to specs using JSONPath expressions to 
-target exactly what we want to change. vaccum now supports a new `apply-overlay` command.
+target exactly what we want to change. vacuum now supports a new `apply-overlay` command.
 
 - [Learn more about the apply-overlay command](https://quobix.com/vacuum/commands/apply-overlay)
 
@@ -249,9 +266,9 @@ New rules:
 
 ---
 
-`v0.17`: **Github Action**.
+`v0.17`: **GitHub Action**.
 
-vacuum now has an official Github Action. [Read the docs](https://quobix.com/vacuum/github-action/), or check it out
+vacuum now has an official GitHub Action. [Read the docs](https://quobix.com/vacuum/github-action/), or check it out
 in the [GitHub Marketplace](https://github.com/marketplace/actions/vacuum-openapi-linter-and-quality-analysis-tool).
 
 ---
@@ -289,17 +306,25 @@ See all the documentation at https://quobix.com/vacuum
 - [Why should you care?](https://quobix.com/vacuum/why/)
 - [Concepts](https://quobix.com/vacuum/concepts/)
 - [FAQ](https://quobix.com/vacuum/faq/)
+- [Ignoring lint results](https://quobix.com/vacuum/ignoring/)
+- [Generate API Docs](https://quobix.com/vacuum/api-docs/)
 - [CLI Commands](https://quobix.com/vacuum/commands/)
   - [lint](https://quobix.com/vacuum/commands/lint/)
   - [vacuum report](https://quobix.com/vacuum/commands/report/)
+  - [docs](https://quobix.com/vacuum/commands/docs/)
   - [dashboard](https://quobix.com/vacuum/commands/dashboard/)
   - [html-report](https://quobix.com/vacuum/commands/html-report/)
   - [bundle](https://quobix.com/vacuum/commands/bundle/)
   - [spectral-report](https://quobix.com/vacuum/commands/spectral-report/)
   - [language-server](https://quobix.com/vacuum/commands/language-server/)
+  - [upgrade](https://quobix.com/vacuum/commands/upgrade/)
   - [apply-overlay](https://quobix.com/vacuum/commands/apply-overlay/)
   - [Change Detection](https://quobix.com/vacuum/commands/change-detection/)
   - [Open Collection](https://quobix.com/vacuum/commands/open-collection/)
+  - [Generate RuleSet](https://quobix.com/vacuum/commands/generate-ruleset/)
+  - [Version](https://quobix.com/vacuum/commands/version/)
+  - [External References](https://quobix.com/vacuum/commands/external-references/)
+  - [Exit Codes](https://quobix.com/vacuum/commands/exit-codes/)
 - [Developer API](https://quobix.com/vacuum/api/getting-started/)
   - [Using The Index](https://quobix.com/vacuum/api/spec-index/)
   - [RuleResultSet](https://quobix.com/vacuum/api/rule-resultset/)
@@ -364,7 +389,7 @@ No external dependencies, the HTML report will run completely offline.
 
 ---
 
-> **_Supports OpenAPI Version 2 (Swagger) and Version 3+_**
+> **_Supports OpenAPI Version 2, OpenAPI Version 3+, and JSON Schema documents_**
 
 You can use either **YAML** or **JSON**, vacuum supports both formats.
 
@@ -481,7 +506,7 @@ recognizes a compressed report file and will deal with it automatically when rea
 
 ## Ignoring specific linting errors
 
-You can ignore specific linting errors by providing an `--ignore-file` argument to the `lint` and `report` commands.
+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`.
 
 ```
 ./vacuum lint --ignore-file <path-to-ignore-file.yaml> -d <your-openapi-spec.yaml>
@@ -491,8 +516,7 @@ 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>
 ```
 
-The ignore-file should point to a .yaml file that contains a list of errors to be ignored by vacuum. The structure of the
-yaml file is as follows:
+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:
 
 ```
 <rule-id-1>:
@@ -525,7 +549,7 @@ if you're interested in seeing how things are progressing, it's available.
 If you're already using Spectral and you have your own [custom ruleset](https://meta.stoplight.io/docs/spectral/e5b9616d6d50c-custom-rulesets#custom-rulesets),
 then you can use it with vacuum! 
 
-The `lint`, `dashboard` and `spectral-report` commands all accept a `-r` or `--ruleset` flag, defining the path to your ruleset file.
+The `lint`, `dashboard`, `docs`, `html-report`, `report`, and `spectral-report` commands all accept a `-r` or `--ruleset` flag, defining the path to your ruleset file.
 
 ### Here are some examples you can try
 
@@ -549,7 +573,7 @@ The `lint`, `dashboard` and `spectral-report` commands all accept a `-r` or `--r
 ./vacuum lint -r rulesets/examples/custom-ruleset.yaml <your-openapi-spec.yaml>
 ```
 
-**_All rules, all of them!**
+**_All rules, all of them!_**
 ```
 ./vacuum lint -r rulesets/examples/all-ruleset.yaml <your-openapi-spec.yaml>
 ```
@@ -588,10 +612,10 @@ Use `--nested-refs-doc-context` or `motor.ExecutionOptions{NestedRefsDocContext:
 ### File
 You can configure vacuum using a configuration file named `vacuum.conf.yaml`
 
-By default, vacuum searches for this file in the following directories
+By default, vacuum searches for this file in the following locations:
 1. Working directory
-2. `$XDG_CONFIG_HOME`
-3. `${HOME}/.config`
+2. `$XDG_CONFIG_HOME`, when set
+3. `${HOME}/.config`, when `$XDG_CONFIG_HOME` is not set
 
 You can also specify a path to a file using the `--config` flag
 
@@ -609,9 +633,9 @@ lint:
   ...
 ```
 
-### Environmental variables
+### Environment variables
 
-You can configure global vacuum flags using environmental variables in the form of: `VACUUM_<flag>`
+You can configure global vacuum flags using environment variables in the form of: `VACUUM_<flag>`
 
 If a flag, has a `-` in it, replace with `_`
 

package/bin/vacuum.js

@@ -6,11 +6,18 @@ import { fileURLToPath } from "url";
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
+const binaryName = process.platform === "win32" ? "vacuum.exe" : "vacuum";
 
 try {
-    execFileSync(path.resolve(`${__dirname}/vacuum`), process.argv.slice(2), {
+    const env = {
+        ...process.env,
+        VACUUM_MANAGED_BY_NPM: "1",
+        VACUUM_MANAGED_PACKAGE_ROOT: path.resolve(`${__dirname}/..`),
+    };
+    execFileSync(path.resolve(__dirname, binaryName), process.argv.slice(2), {
         stdio: "inherit",
+        env,
     });
 } catch (e) {
-    exit(1)
+    exit(typeof e.status === "number" ? e.status : 1)
 }

package/npm-install/postinstall.js

@@ -1,6 +1,6 @@
 import { createWriteStream } from "fs";
 import * as fs from "fs/promises";
-import fetch from "node-fetch";
+import https from "https";
 import { HttpsProxyAgent } from "https-proxy-agent";
 import { pipeline } from "stream/promises";
 import * as tar from "tar";
@@ -18,6 +18,47 @@ function getProxyUrl() {
            null;
 }
 
+function createRequestOptions() {
+    const proxyUrl = getProxyUrl();
+    if (!proxyUrl) {
+        return {};
+    }
+    console.log("Using proxy:", proxyUrl);
+    return { agent: new HttpsProxyAgent(proxyUrl) };
+}
+
+function requestUrl(url, options, redirectsRemaining = 5) {
+    return new Promise((resolve, reject) => {
+        const request = https.get(url, options, (response) => {
+            const { statusCode, headers } = response;
+            const location = headers.location;
+
+            if (statusCode >= 300 && statusCode < 400 && location) {
+                response.resume();
+                if (redirectsRemaining <= 0) {
+                    reject(new Error("Too many redirects while fetching the binary"));
+                    return;
+                }
+                const nextUrl = new URL(location, url).toString();
+                requestUrl(nextUrl, options, redirectsRemaining - 1).then(resolve, reject);
+                return;
+            }
+
+            resolve(response);
+        });
+        request.on("error", reject);
+    });
+}
+
+async function downloadFile(url, destination) {
+    const response = await requestUrl(url, createRequestOptions());
+    if (response.statusCode < 200 || response.statusCode > 299) {
+        response.resume();
+        throw new Error("Failed fetching the binary: " + response.statusMessage);
+    }
+    await pipeline(response, createWriteStream(destination));
+}
+
 async function install() {
     if (process.platform === "android") {
         console.log("Installing, may take a moment...");
@@ -43,24 +84,11 @@ async function install() {
     url = url.replace(/{{version}}/g, version);
     url = url.replace(/{{bin_name}}/g, binName);
 
-    // Configure fetch options with proxy support
-    const fetchOptions = {};
-    const proxyUrl = getProxyUrl();
-    if (proxyUrl) {
-        console.log('Using proxy:', proxyUrl);
-        fetchOptions.agent = new HttpsProxyAgent(proxyUrl);
-    }
-
-    console.log('fetching from URL', url)
-    const response = await fetch(url, fetchOptions);
-    if (!response.ok) {
-        throw new Error("Failed fetching the binary: " + response.statusText);
-    }
-
     const tarFile = "downloaded.tar.gz";
 
     await fs.mkdir(binPath, { recursive: true });
-    await pipeline(response.body, createWriteStream(tarFile));
+    console.log("fetching from URL", url);
+    await downloadFile(url, tarFile);
     await tar.x({ file: tarFile, cwd: binPath });
     await fs.rm(tarFile);
 }
@@ -72,4 +100,4 @@ install()
     .catch(async (err) => {
         console.error(err);
         process.exit(1);
-    });
+    });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quobix/vacuum",
-  "version": "0.27.0",
+  "version": "0.27.2",
   "description": "The world's fastest, most scalable and complete OpenAPI parser",
   "type": "module",
   "author": "Dave Shanley",
@@ -11,7 +11,7 @@
     "url": "git+https://github.com/daveshanley/vacuum.git"
   },
   "engines": {
-    "node": ">=16.0.0"
+    "node": ">=24.16.0"
   },
   "scripts": {
     "postinstall": "node ./npm-install/postinstall.js"
@@ -23,12 +23,11 @@
     "npm-install"
   ],
   "dependencies": {
-    "https-proxy-agent": "^7.0.6",
-    "node-fetch": "^3.3.2",
-    "tar": "^7.5.13"
+    "https-proxy-agent": "^9.0.0",
+    "tar": "^7.5.15"
   },
   "devDependencies": {
-    "@sourcemeta/jsonschema": "^11.5.1"
+    "@sourcemeta/jsonschema": "^15.6.3"
   },
   "bugs": {
     "url": "https://github.com/daveshanley/vacuum/issues"