feat: add input validation with descriptive errors to public API functions

Signed-off-by: leocavalcante <[email protected]>

Author: leocavalcante

src/paths.mjs

@@ -22,8 +22,17 @@ export const REQUIRED_FRONTMATTER_FIELDS = ["version", "requires"]
  * Get the package root directory from a module's import.meta.url
  * @param {string} importMetaUrl - The import.meta.url of the calling module
  * @returns {string} The package root directory path
+ * @throws {TypeError} If importMetaUrl is not a non-empty string
  */
 export function getPackageRoot(importMetaUrl) {
+	if (typeof importMetaUrl !== "string") {
+		throw new TypeError(
+			`getPackageRoot: importMetaUrl must be a string, got ${importMetaUrl === null ? "null" : typeof importMetaUrl}`,
+		)
+	}
+	if (importMetaUrl.trim() === "") {
+		throw new TypeError("getPackageRoot: importMetaUrl must not be empty")
+	}
 	const __filename = fileURLToPath(importMetaUrl)
 	const __dirname = dirname(__filename)
 	// Both postinstall.mjs and preuninstall.mjs are in the package root
@@ -34,8 +43,17 @@ export function getPackageRoot(importMetaUrl) {
  * Get the source directory containing agent markdown files.
  * @param {string} packageRoot - The package root directory
  * @returns {string} Path to the agents source directory
+ * @throws {TypeError} If packageRoot is not a non-empty string
  */
 export function getAgentsSourceDir(packageRoot) {
+	if (typeof packageRoot !== "string") {
+		throw new TypeError(
+			`getAgentsSourceDir: packageRoot must be a string, got ${packageRoot === null ? "null" : typeof packageRoot}`,
+		)
+	}
+	if (packageRoot.trim() === "") {
+		throw new TypeError("getAgentsSourceDir: packageRoot must not be empty")
+	}
 	return join(packageRoot, "agents")
 }
 
@@ -337,8 +355,25 @@ function compareVersions(a, b) {
  * checkVersionCompatibility("^1.0.0", "2.0.0")  // false
  * checkVersionCompatibility("~1.2.0", "1.2.5")  // true
  * checkVersionCompatibility("~1.2.0", "1.3.0")  // false
+ * @throws {TypeError} If required or current is not a non-empty string
  */
 export function checkVersionCompatibility(required, current) {
+	if (typeof required !== "string") {
+		throw new TypeError(
+			`checkVersionCompatibility: required must be a string, got ${required === null ? "null" : typeof required}`,
+		)
+	}
+	if (required.trim() === "") {
+		throw new TypeError("checkVersionCompatibility: required must not be empty")
+	}
+	if (typeof current !== "string") {
+		throw new TypeError(
+			`checkVersionCompatibility: current must be a string, got ${current === null ? "null" : typeof current}`,
+		)
+	}
+	if (current.trim() === "") {
+		throw new TypeError("checkVersionCompatibility: current must not be empty")
+	}
 	const currentVersion = parseVersion(current)
 	if (!currentVersion) return false
 
@@ -431,8 +466,14 @@ export function checkVersionCompatibility(required, current) {
  * // Parse custom arguments
  * const flags = parseCliFlags(["node", "script.js", "--verbose", "--dry-run"])
  * // flags = { dryRun: true, verbose: true, help: false }
+ * @throws {TypeError} If argv is not an array
  */
 export function parseCliFlags(argv) {
+	if (!Array.isArray(argv)) {
+		throw new TypeError(
+			`parseCliFlags: argv must be an array, got ${argv === null ? "null" : typeof argv}`,
+		)
+	}
 	return {
 		dryRun: argv.includes("--dry-run"),
 		verbose: argv.includes("--verbose"),

tests/paths.test.ts

@@ -48,6 +48,41 @@ describe("paths.mjs exports", () => {
 			const result2 = getPackageRoot(import.meta.url)
 			expect(result1).toBe(result2)
 		})
+
+		it("should throw TypeError for null input", () => {
+			expect(() => getPackageRoot(null as unknown as string)).toThrow(TypeError)
+			expect(() => getPackageRoot(null as unknown as string)).toThrow(
+				"getPackageRoot: importMetaUrl must be a string, got null",
+			)
+		})
+
+		it("should throw TypeError for undefined input", () => {
+			expect(() => getPackageRoot(undefined as unknown as string)).toThrow(TypeError)
+			expect(() => getPackageRoot(undefined as unknown as string)).toThrow(
+				"getPackageRoot: importMetaUrl must be a string, got undefined",
+			)
+		})
+
+		it("should throw TypeError for non-string input", () => {
+			expect(() => getPackageRoot(123 as unknown as string)).toThrow(TypeError)
+			expect(() => getPackageRoot(123 as unknown as string)).toThrow(
+				"getPackageRoot: importMetaUrl must be a string, got number",
+			)
+			expect(() => getPackageRoot({} as unknown as string)).toThrow(TypeError)
+			expect(() => getPackageRoot({} as unknown as string)).toThrow(
+				"getPackageRoot: importMetaUrl must be a string, got object",
+			)
+		})
+
+		it("should throw TypeError for empty string input", () => {
+			expect(() => getPackageRoot("")).toThrow(TypeError)
+			expect(() => getPackageRoot("")).toThrow("getPackageRoot: importMetaUrl must not be empty")
+		})
+
+		it("should throw TypeError for whitespace-only string input", () => {
+			expect(() => getPackageRoot("   ")).toThrow(TypeError)
+			expect(() => getPackageRoot("   ")).toThrow("getPackageRoot: importMetaUrl must not be empty")
+		})
 	})
 
 	describe("getAgentsSourceDir", () => {
@@ -82,6 +117,45 @@ describe("paths.mjs exports", () => {
 			const result = getAgentsSourceDir(packageRoot)
 			expect(result).toBe(join(packageRoot, "agents"))
 		})
+
+		it("should throw TypeError for null input", () => {
+			expect(() => getAgentsSourceDir(null as unknown as string)).toThrow(TypeError)
+			expect(() => getAgentsSourceDir(null as unknown as string)).toThrow(
+				"getAgentsSourceDir: packageRoot must be a string, got null",
+			)
+		})
+
+		it("should throw TypeError for undefined input", () => {
+			expect(() => getAgentsSourceDir(undefined as unknown as string)).toThrow(TypeError)
+			expect(() => getAgentsSourceDir(undefined as unknown as string)).toThrow(
+				"getAgentsSourceDir: packageRoot must be a string, got undefined",
+			)
+		})
+
+		it("should throw TypeError for non-string input", () => {
+			expect(() => getAgentsSourceDir(123 as unknown as string)).toThrow(TypeError)
+			expect(() => getAgentsSourceDir(123 as unknown as string)).toThrow(
+				"getAgentsSourceDir: packageRoot must be a string, got number",
+			)
+			expect(() => getAgentsSourceDir({} as unknown as string)).toThrow(TypeError)
+			expect(() => getAgentsSourceDir({} as unknown as string)).toThrow(
+				"getAgentsSourceDir: packageRoot must be a string, got object",
+			)
+		})
+
+		it("should throw TypeError for empty string input", () => {
+			expect(() => getAgentsSourceDir("")).toThrow(TypeError)
+			expect(() => getAgentsSourceDir("")).toThrow(
+				"getAgentsSourceDir: packageRoot must not be empty",
+			)
+		})
+
+		it("should throw TypeError for whitespace-only string input", () => {
+			expect(() => getAgentsSourceDir("   ")).toThrow(TypeError)
+			expect(() => getAgentsSourceDir("   ")).toThrow(
+				"getAgentsSourceDir: packageRoot must not be empty",
+			)
+		})
 	})
 
 	describe("AGENTS_TARGET_DIR", () => {
@@ -790,14 +864,94 @@ This is a test agent that handles various tasks.
 				expect(checkVersionCompatibility(">=1.0.0", "invalid")).toBe(false)
 				expect(checkVersionCompatibility(">=1.0.0", "1.0")).toBe(false)
 				expect(checkVersionCompatibility(">=1.0.0", "1")).toBe(false)
-				expect(checkVersionCompatibility(">=1.0.0", "")).toBe(false)
 			})
 
 			it("should return false for invalid required version", () => {
 				expect(checkVersionCompatibility("invalid", "1.0.0")).toBe(false)
 				expect(checkVersionCompatibility(">=invalid", "1.0.0")).toBe(false)
 				expect(checkVersionCompatibility("^", "1.0.0")).toBe(false)
-				expect(checkVersionCompatibility("", "1.0.0")).toBe(false)
+			})
+
+			it("should throw TypeError for null required", () => {
+				expect(() => checkVersionCompatibility(null as unknown as string, "1.0.0")).toThrow(
+					TypeError,
+				)
+				expect(() => checkVersionCompatibility(null as unknown as string, "1.0.0")).toThrow(
+					"checkVersionCompatibility: required must be a string, got null",
+				)
+			})
+
+			it("should throw TypeError for undefined required", () => {
+				expect(() => checkVersionCompatibility(undefined as unknown as string, "1.0.0")).toThrow(
+					TypeError,
+				)
+				expect(() => checkVersionCompatibility(undefined as unknown as string, "1.0.0")).toThrow(
+					"checkVersionCompatibility: required must be a string, got undefined",
+				)
+			})
+
+			it("should throw TypeError for non-string required", () => {
+				expect(() => checkVersionCompatibility(123 as unknown as string, "1.0.0")).toThrow(
+					TypeError,
+				)
+				expect(() => checkVersionCompatibility(123 as unknown as string, "1.0.0")).toThrow(
+					"checkVersionCompatibility: required must be a string, got number",
+				)
+			})
+
+			it("should throw TypeError for empty string required", () => {
+				expect(() => checkVersionCompatibility("", "1.0.0")).toThrow(TypeError)
+				expect(() => checkVersionCompatibility("", "1.0.0")).toThrow(
+					"checkVersionCompatibility: required must not be empty",
+				)
+			})
+
+			it("should throw TypeError for whitespace-only required", () => {
+				expect(() => checkVersionCompatibility("   ", "1.0.0")).toThrow(TypeError)
+				expect(() => checkVersionCompatibility("   ", "1.0.0")).toThrow(
+					"checkVersionCompatibility: required must not be empty",
+				)
+			})
+
+			it("should throw TypeError for null current", () => {
+				expect(() => checkVersionCompatibility(">=1.0.0", null as unknown as string)).toThrow(
+					TypeError,
+				)
+				expect(() => checkVersionCompatibility(">=1.0.0", null as unknown as string)).toThrow(
+					"checkVersionCompatibility: current must be a string, got null",
+				)
+			})
+
+			it("should throw TypeError for undefined current", () => {
+				expect(() => checkVersionCompatibility(">=1.0.0", undefined as unknown as string)).toThrow(
+					TypeError,
+				)
+				expect(() => checkVersionCompatibility(">=1.0.0", undefined as unknown as string)).toThrow(
+					"checkVersionCompatibility: current must be a string, got undefined",
+				)
+			})
+
+			it("should throw TypeError for non-string current", () => {
+				expect(() => checkVersionCompatibility(">=1.0.0", 100 as unknown as string)).toThrow(
+					TypeError,
+				)
+				expect(() => checkVersionCompatibility(">=1.0.0", 100 as unknown as string)).toThrow(
+					"checkVersionCompatibility: current must be a string, got number",
+				)
+			})
+
+			it("should throw TypeError for empty string current", () => {
+				expect(() => checkVersionCompatibility(">=1.0.0", "")).toThrow(TypeError)
+				expect(() => checkVersionCompatibility(">=1.0.0", "")).toThrow(
+					"checkVersionCompatibility: current must not be empty",
+				)
+			})
+
+			it("should throw TypeError for whitespace-only current", () => {
+				expect(() => checkVersionCompatibility(">=1.0.0", "   ")).toThrow(TypeError)
+				expect(() => checkVersionCompatibility(">=1.0.0", "   ")).toThrow(
+					"checkVersionCompatibility: current must not be empty",
+				)
 			})
 		})
 	})
@@ -861,6 +1015,35 @@ This is a test agent that handles various tasks.
 			expect(result.dryRun).toBe(false)
 			expect(result.verbose).toBe(false)
 		})
+
+		it("should throw TypeError for null input", () => {
+			expect(() => parseCliFlags(null as unknown as string[])).toThrow(TypeError)
+			expect(() => parseCliFlags(null as unknown as string[])).toThrow(
+				"parseCliFlags: argv must be an array, got null",
+			)
+		})
+
+		it("should throw TypeError for undefined input", () => {
+			expect(() => parseCliFlags(undefined as unknown as string[])).toThrow(TypeError)
+			expect(() => parseCliFlags(undefined as unknown as string[])).toThrow(
+				"parseCliFlags: argv must be an array, got undefined",
+			)
+		})
+
+		it("should throw TypeError for non-array input", () => {
+			expect(() => parseCliFlags("string" as unknown as string[])).toThrow(TypeError)
+			expect(() => parseCliFlags("string" as unknown as string[])).toThrow(
+				"parseCliFlags: argv must be an array, got string",
+			)
+			expect(() => parseCliFlags(123 as unknown as string[])).toThrow(TypeError)
+			expect(() => parseCliFlags(123 as unknown as string[])).toThrow(
+				"parseCliFlags: argv must be an array, got number",
+			)
+			expect(() => parseCliFlags({} as unknown as string[])).toThrow(TypeError)
+			expect(() => parseCliFlags({} as unknown as string[])).toThrow(
+				"parseCliFlags: argv must be an array, got object",
+			)
+		})
 	})
 
 	describe("createLogger", () => {