@kubb/core 5.11.6 → 5.12.1

package/dist/index.cjs

@@ -32,8 +32,12 @@ node_path = __toESM(node_path, 1);
 let node_fs = require("node:fs");
 let node_util = require("node:util");
 let _kubb_ast = require("@kubb/ast");
-let node_crypto = require("node:crypto");
+let node_dns = require("node:dns");
+node_dns = __toESM(node_dns, 1);
+let node_net = require("node:net");
+node_net = __toESM(node_net, 1);
 let node_os = require("node:os");
+let node_crypto = require("node:crypto");
 let node_readline = require("node:readline");
 let unstorage = require("unstorage");
 let unstorage_drivers_fs = require("unstorage/drivers/fs");
@@ -41,7 +45,7 @@ unstorage_drivers_fs = __toESM(unstorage_drivers_fs, 1);
 let node_url = require("node:url");
 let node_module = require("node:module");
 //#region package.json
-var version = "5.11.6";
+var version = "5.12.1";
 //#endregion
 //#region ../../internals/utils/src/casing.ts
 /**
@@ -529,6 +533,12 @@ const diagnosticCatalog = {
 		cause: "A URL set as `input` (or reached through a `$ref`) never answered, so the request failed before a status came back. A refused connection, an unknown host, an expired certificate, and a timeout all land here.",
 		fix: "Check that the host is running and reachable from this machine. For a local server, start it and confirm the port matches the one in `input`."
 	},
+	gitInputFailed: {
+		code: "KUBB_GIT_INPUT_FAILED",
+		title: "Git input failed",
+		cause: "A git `input` (`git+<repo>#<ref>:<path>`) is malformed, or `git` could not fetch it: git is not installed, the repository or ref does not exist, or the credentials were refused.",
+		fix: "Write the input as `git+<repo>#<ref>:<path>`. Run `git fetch --depth 1 <repo> <ref>` yourself to see the git error, and set up a credential helper or SSH key for a private repository."
+	},
 	inputRequired: {
 		code: "KUBB_INPUT_REQUIRED",
 		title: "Input required",
@@ -1417,18 +1427,209 @@ function definePlugin(definition) {
 	});
 }
 //#endregion
+//#region src/publicAddress.ts
+function createBlockList() {
+	const list = new node_net.default.BlockList();
+	for (const [address, prefix] of [
+		["0.0.0.0", 8],
+		["10.0.0.0", 8],
+		["100.64.0.0", 10],
+		["127.0.0.0", 8],
+		["169.254.0.0", 16],
+		["172.16.0.0", 12],
+		["192.0.0.0", 24],
+		["192.168.0.0", 16],
+		["198.18.0.0", 15],
+		["224.0.0.0", 3]
+	]) list.addSubnet(address, prefix, "ipv4");
+	for (const [address, prefix] of [
+		["::", 128],
+		["::1", 128],
+		["64:ff9b::", 96],
+		["fc00::", 7],
+		["fe80::", 10],
+		["ff00::", 8]
+	]) list.addSubnet(address, prefix, "ipv6");
+	return list;
+}
+const privateAddresses = createBlockList();
+/**
+* Whether `address` is a routable public IP. Loopback, private, link-local, cloud metadata, and
+* multicast ranges are not, and an IPv4-mapped IPv6 address counts as the IPv4 address it wraps.
+* Pass `blocked` to replace the ranges.
+*/
+function isPublicAddress(address, blocked = privateAddresses) {
+	const family = node_net.default.isIP(address);
+	return family !== 0 && !blocked.check(address, family === 4 ? "ipv4" : "ipv6");
+}
+//#endregion
+//#region src/gitInput.ts
+/** Matches a git `input`: the `git+` prefix npm uses for git dependencies. */
+const gitInputRegExp = /^git\+/i;
+function gitError(message, cause) {
+	return new Diagnostics.Error({
+		code: Diagnostics.code.gitInputFailed,
+		severity: "error",
+		message,
+		help: "Write a git `input` as `git+<repo>#<ref>:<path>`, for example `git+https://github.com/org/api.git#main:specs/openapi.yaml`. Check that `git` is installed and that `git fetch` can reach the repository with your credentials.",
+		location: { kind: "config" },
+		cause: cause === void 0 ? void 0 : toError(cause)
+	});
+}
+/** The repository URL without a user or password, safe to print. */
+function redact(repo) {
+	if (!URL.canParse(repo)) return repo;
+	const url = new URL(repo);
+	url.username = "";
+	url.password = "";
+	return url.href;
+}
+/**
+* Splits `git+<repo>#<ref>:<path>` into its parts. Git refs cannot contain `:`, so the first one
+* in the fragment ends the ref. Throws `KUBB_GIT_INPUT_FAILED` when the fragment or path is missing.
+*/
+function parseGitInput(input) {
+	const hashIndex = input.indexOf("#");
+	const repo = input.slice(4, hashIndex === -1 ? void 0 : hashIndex);
+	const fragment = hashIndex === -1 ? "" : input.slice(hashIndex + 1);
+	const colonIndex = fragment.indexOf(":");
+	const ref = colonIndex === -1 ? void 0 : fragment.slice(0, colonIndex);
+	const path = colonIndex === -1 ? fragment : fragment.slice(colonIndex + 1);
+	if (!repo || !path || ref === "") throw gitError(`The git \`input\` for ${redact(repo)} has no repository, ref, or spec path after \`#\`.`);
+	return {
+		repo,
+		ref,
+		path
+	};
+}
+/**
+* The `git -c` settings that confine a fetch to https and to `addresses`: the connection goes to
+* the addresses already checked, whatever the host answers to a second lookup, and a redirect to
+* another host is an error. Needs git 2.37 for the pinning.
+*
+* @internal
+*/
+function publicFetchConfig({ host, port, addresses }) {
+	const pinned = addresses.map((address) => node_net.default.isIPv6(address) ? `[${address}]` : address).join(",");
+	const config = [
+		"http.followRedirects=false",
+		"protocol.allow=never",
+		"protocol.https.allow=always"
+	];
+	if (!node_net.default.isIP(host)) config.push(`http.curloptResolve=${host}:${port}:${pinned}`);
+	return config.flatMap((setting) => ["-c", setting]);
+}
+async function resolvePublicFetchConfig(repo, signal) {
+	if (!URL.canParse(repo) || new URL(repo).protocol !== "https:") throw gitError("A public git `input` must be an https repository URL, not an ssh, git, or file address.");
+	const url = new URL(repo);
+	const host = url.hostname.replace(/^\[|\]$/g, "");
+	const isLiteral = node_net.default.isIP(host) !== 0;
+	const addresses = isLiteral ? [host] : (await node_dns.default.promises.lookup(host, { all: true })).map(({ address }) => address);
+	if (!addresses.length || addresses.some((address) => !isPublicAddress(address))) throw gitError(`${host} is not a public address, so this git \`input\` is not fetched.`);
+	if (!isLiteral) {
+		const { stdout } = await (0, tinyexec.x)("git", ["--version"], {
+			nodeOptions: { signal },
+			throwOnError: true
+		});
+		const [, major = 0, minor = 0] = /(\d+)\.(\d+)/.exec(stdout)?.map(Number) ?? [];
+		if (major < 2 || major === 2 && minor < 37) throw gitError(`Fetching a public git \`input\` needs git 2.37 or newer, found ${stdout.trim()}.`);
+	}
+	return publicFetchConfig({
+		host,
+		port: url.port || "443",
+		addresses
+	});
+}
+/**
+* Fetches one commit of a git repository into a temporary directory with a shallow `git fetch`,
+* so any host and the user's own git credentials work, and relative `$ref` files resolve.
+* Resolves to the spec path on disk and a `dispose` that deletes the checkout.
+*
+* With `publicOnly`, the repository must be an https URL on public addresses, the fetch connects to
+* the addresses checked, and it does not follow a redirect.
+*/
+async function checkoutGitInput(input, signal, { publicOnly = false } = {}) {
+	const { repo, ref, path } = parseGitInput(input);
+	const fetchConfig = publicOnly ? await resolvePublicFetchConfig(repo, signal) : [];
+	const dir = await (0, node_fs_promises.mkdtemp)((0, node_path.join)((0, node_os.tmpdir)(), "kubb-git-"));
+	const dispose = () => (0, node_fs_promises.rm)(dir, {
+		recursive: true,
+		force: true
+	});
+	const specPath = (0, node_path.resolve)(dir, path);
+	const relativePath = (0, node_path.relative)(dir, specPath);
+	if (relativePath === ".." || relativePath.startsWith(`..${node_path.sep}`) || (0, node_path.isAbsolute)(relativePath)) {
+		await dispose();
+		throw gitError(`The spec path "${path}" in the git \`input\` points outside the repository.`);
+	}
+	const label = `${redact(repo)}${ref ? ` at ${ref}` : ""}`;
+	const env = {
+		...node_process.default.env,
+		GIT_TERMINAL_PROMPT: "0"
+	};
+	const steps = [
+		["init", "--quiet"],
+		[
+			"config",
+			"core.symlinks",
+			"false"
+		],
+		[
+			...fetchConfig,
+			"fetch",
+			"--quiet",
+			"--depth",
+			"1",
+			"--end-of-options",
+			repo,
+			ref ?? "HEAD"
+		],
+		[
+			"checkout",
+			"--quiet",
+			"FETCH_HEAD"
+		]
+	];
+	try {
+		for (const args of steps) {
+			const result = await (0, tinyexec.x)("git", args, {
+				nodeOptions: {
+					cwd: dir,
+					env,
+					signal
+				},
+				throwOnError: false
+			});
+			if (result.exitCode !== 0) {
+				const stderr = result.stderr.replaceAll(repo, redact(repo)).trim();
+				throw gitError(`\`git ${args[0]}\` failed for ${label}: ${stderr || `exit code ${result.exitCode}`}`);
+			}
+		}
+	} catch (error) {
+		await dispose();
+		if (Diagnostics.isError(error)) throw error;
+		throw gitError(`Cannot run \`git\` for ${label}: ${getErrorMessage(error)}`, error);
+	}
+	return {
+		path: specPath,
+		dispose
+	};
+}
+//#endregion
 //#region src/input.ts
 /**
 * Classifies an `input` value so callers branch on it once instead of repeating the checks.
 *
 * A non-string is a parsed spec (`object`). A string is `inline` when it holds OpenAPI content,
 * meaning it starts with `{` or `[`, spans multiple lines, or opens with a YAML `openapi:` or
-* `swagger:` key. Otherwise a string is a `url` when it parses as one, or a `file` path.
+* `swagger:` key. Otherwise a string is `git` when it starts with `git+`, a `url` when it parses as
+* one, or a `file` path.
 */
 function getInputKind(input) {
 	if (typeof input !== "string") return "object";
 	const trimmed = input.trimStart();
 	if (trimmed.startsWith("{") || trimmed.startsWith("[") || input.includes("\n") || /^(openapi|swagger)\s*:/i.test(trimmed)) return "inline";
+	if (gitInputRegExp.test(input)) return "git";
 	if (URL.canParse(input)) return "url";
 	return "file";
 }
@@ -1452,8 +1653,9 @@ function isLegacyInput(input) {
 /**
 * Normalizes `config.input` into an `AdapterSource` the adapter can parse.
 *
-* A parsed object and inline content become `{ type: 'data' }`; a URL is kept verbatim and a
-* local path is resolved against `config.root`, both as `{ type: 'path' }`.
+* A parsed object and inline content become `{ type: 'data' }`; a URL or git input is kept
+* verbatim and a local path is resolved against `config.root`, all as `{ type: 'path' }`. The
+* driver checks out a git input before the adapter parses it.
 */
 function inputToAdapterSource(config) {
 	const input = config.input;
@@ -1480,7 +1682,7 @@ function inputToAdapterSource(config) {
 		type: "data",
 		data: input
 	};
-	if (kind === "url") return {
+	if (kind === "url" || kind === "git") return {
 		type: "path",
 		path: input
 	};
@@ -2414,13 +2616,20 @@ var KubbDriver = class {
 	async #parseInput() {
 		if (this.inputNode || !this.adapter || !this.#adapterSource) return;
 		this.options.signal?.throwIfAborted();
+		const source = this.#adapterSource;
+		const checkout = source.type === "path" && gitInputRegExp.test(source.path) ? await checkoutGitInput(source.path, this.options.signal) : void 0;
 		try {
-			this.inputNode = await this.adapter.parse(this.#adapterSource, { signal: this.options.signal });
+			this.inputNode = await this.adapter.parse(checkout ? {
+				type: "path",
+				path: checkout.path
+			} : source, { signal: this.options.signal });
 		} catch (caughtError) {
 			throw new Diagnostics.Error(Diagnostics.fromExtension(caughtError, {
 				kind: "adapter",
 				extension: this.adapter
 			}));
+		} finally {
+			await checkout?.dispose();
 		}
 	}
 	/**
@@ -4262,6 +4471,7 @@ exports.addMacro = addMacro;
 exports.assertPluginOption = assertPluginOption;
 exports.cacheStorage = cacheStorage;
 exports.checkCompatibility = checkCompatibility;
+exports.checkoutGitInput = checkoutGitInput;
 exports.cliReporter = cliReporter;
 exports.createAdapter = createAdapter;
 exports.createCliReporter = createCliReporter;
@@ -4282,6 +4492,7 @@ exports.htmlReporter = htmlReporter;
 exports.injectFile = injectFile;
 exports.isExtensionManifest = isExtensionManifest;
 exports.isPackageName = isPackageName;
+exports.isPublicAddress = isPublicAddress;
 exports.isRegistryEntry = isRegistryEntry;
 exports.jsonReporter = jsonReporter;
 exports.kubbContext = kubbContext;