docs(test): add documentation comments to PBT explaining replaced tests

- Add JSDoc comments explaining what example-based tests were replaced
- Add inline comments with concrete examples for each property test
- Restore 'should handle arrays correctly within objects' test for clarity
- Keep concrete examples as documentation alongside PBT

Author: ryoppippi

src/requestBuilder.test.ts

@@ -394,6 +394,25 @@ describe('RequestBuilder', () => {
 			expect(url.searchParams.get('filter[validField]')).toBe('test');
 		});
 
+		it('should handle arrays correctly within objects', async () => {
+			const params = {
+				pathParam: 'test-value',
+				filter: {
+					arrayField: [1, 2, 3],
+					stringArray: ['a', 'b', 'c'],
+					mixed: ['string', 42, true],
+				},
+			};
+
+			const result = await builder.execute(params, { dryRun: true });
+			const url = new URL(result.url as string);
+
+			// Arrays should be converted to JSON strings
+			expect(url.searchParams.get('filter[arrayField]')).toBe('[1,2,3]');
+			expect(url.searchParams.get('filter[stringArray]')).toBe('["a","b","c"]');
+			expect(url.searchParams.get('filter[mixed]')).toBe('["string",42,true]');
+		});
+
 		it('should handle nested objects with special types at runtime', async () => {
 			// Test runtime serialization of nested non-JSON types
 			const params = {
@@ -474,6 +493,24 @@ describe('RequestBuilder', () => {
 	});
 });
 
+/**
+ * Property-Based Tests for RequestBuilder
+ *
+ * These tests verify invariants that must hold for ANY valid input,
+ * replacing/supplementing example-based tests:
+ *
+ * Parameter Key Validation (replaces "should validate parameter keys and reject invalid characters"):
+ *   - Valid: "user_id", "filter.name", "x-custom-field" => accepted
+ *   - Invalid: "invalid key with spaces", "key@special!" => throws "Invalid parameter key"
+ *
+ * Value Serialization (supplements "should handle arrays correctly within objects" - kept for clarity):
+ *   - { arrayField: [1, 2, 3] } => filter[arrayField]="[1,2,3]"
+ *   - { stringArray: ["a", "b"] } => filter[stringArray]='["a","b"]'
+ *
+ * Deep Object Nesting (replaces "should throw error when recursion depth limit is exceeded"):
+ *   - { nested: { nested: { value: "ok" } } } (depth 3) => accepted
+ *   - { nested: { nested: { ... 12 levels ... } } } => throws "Maximum nesting depth (10) exceeded"
+ */
 describe('RequestBuilder - Property-Based Tests', () => {
 	const baseConfig = {
 		kind: 'http',
@@ -491,7 +528,14 @@ describe('RequestBuilder - Property-Based Tests', () => {
 		.string({ minLength: 1, maxLength: 20 })
 		.filter((s) => /[^a-zA-Z0-9_.-]/.test(s) && s.trim().length > 0);
 
+	/**
+	 * Parameter Key Validation
+	 *
+	 * Examples of valid keys: "user_id", "filter.name", "X-Custom-Header"
+	 * Examples of invalid keys: "invalid key", "special@char", "has spaces"
+	 */
 	describe('Parameter Key Validation', () => {
+		// Example: { filter: { user_id: "123" } } => ?filter[user_id]=123 (no error)
 		fcTest.prop([validKeyArbitrary, fc.string()], { numRuns: 100 })(
 			'accepts valid parameter keys',
 			async (key, value) => {
@@ -506,6 +550,7 @@ describe('RequestBuilder - Property-Based Tests', () => {
 			},
 		);
 
+		// Example: { filter: { "invalid key with spaces": "test" } } => throws Error
 		fcTest.prop([invalidKeyArbitrary, fc.string()], { numRuns: 100 })(
 			'rejects invalid parameter keys',
 			async (key, value) => {
@@ -521,6 +566,14 @@ describe('RequestBuilder - Property-Based Tests', () => {
 		);
 	});
 
+	/**
+	 * Header Management
+	 *
+	 * Examples:
+	 * - new RequestBuilder(config, { "Auth": "token" }).setHeaders({ "X-Api": "key" })
+	 *   => getHeaders() returns { "Auth": "token", "X-Api": "key" }
+	 * - prepareHeaders() always includes "User-Agent: stackone-ai-node"
+	 */
 	describe('Header Management', () => {
 		// Arbitrary for header key-value pairs
 		const headerArbitrary = fc.dictionary(
@@ -529,6 +582,7 @@ describe('RequestBuilder - Property-Based Tests', () => {
 			{ minKeys: 1, maxKeys: 5 },
 		);
 
+		// Example: init with {"A": "1"}, setHeaders({"B": "2"}) => {"A": "1", "B": "2"}
 		fcTest.prop([headerArbitrary, headerArbitrary], { numRuns: 50 })(
 			'setHeaders accumulates headers without losing existing ones',
 			(headers1, headers2) => {
@@ -549,6 +603,7 @@ describe('RequestBuilder - Property-Based Tests', () => {
 			},
 		);
 
+		// Example: prepareHeaders() => { "User-Agent": "stackone-ai-node", ...customHeaders }
 		fcTest.prop([headerArbitrary], { numRuns: 50 })(
 			'prepareHeaders always includes User-Agent',
 			(headers) => {
@@ -559,6 +614,7 @@ describe('RequestBuilder - Property-Based Tests', () => {
 			},
 		);
 
+		// Example: const h = getHeaders(); h["X"] = "Y"; getHeaders()["X"] is still undefined
 		fcTest.prop([headerArbitrary], { numRuns: 50 })(
 			'getHeaders returns a copy, not the original',
 			(headers) => {
@@ -573,7 +629,18 @@ describe('RequestBuilder - Property-Based Tests', () => {
 		);
 	});
 
+	/**
+	 * Value Serialization
+	 *
+	 * Examples:
+	 * - { key: "hello" } => ?filter[key]=hello
+	 * - { key: 42 } => ?filter[key]=42
+	 * - { key: true } => ?filter[key]=true
+	 * - { key: [1, 2, 3] } => ?filter[key]=[1,2,3]
+	 * - { key: ["a", "b"] } => ?filter[key]=["a","b"]
+	 */
 	describe('Value Serialization', () => {
+		// Example: { filter: { key: "hello world" } } => ?filter[key]=hello%20world
 		fcTest.prop([fc.string()], { numRuns: 100 })(
 			'string values serialize to themselves',
 			async (str) => {
@@ -587,6 +654,7 @@ describe('RequestBuilder - Property-Based Tests', () => {
 			},
 		);
 
+		// Example: { filter: { key: 42 } } => ?filter[key]=42
 		fcTest.prop([fc.integer()], { numRuns: 100 })(
 			'integer values serialize to string',
 			async (num) => {
@@ -600,6 +668,7 @@ describe('RequestBuilder - Property-Based Tests', () => {
 			},
 		);
 
+		// Example: { filter: { key: true } } => ?filter[key]=true
 		fcTest.prop([fc.boolean()], { numRuns: 10 })(
 			'boolean values serialize to string',
 			async (bool) => {
@@ -613,6 +682,8 @@ describe('RequestBuilder - Property-Based Tests', () => {
 			},
 		);
 
+		// Example: { filter: { key: [1, 2, 3] } } => ?filter[key]=[1,2,3]
+		// Example: { filter: { key: ["a", "b"] } } => ?filter[key]=["a","b"]
 		fcTest.prop(
 			[fc.array(fc.oneof(fc.string(), fc.integer(), fc.boolean()), { minLength: 1, maxLength: 5 })],
 			{
@@ -629,7 +700,16 @@ describe('RequestBuilder - Property-Based Tests', () => {
 		});
 	});
 
+	/**
+	 * Deep Object Nesting
+	 *
+	 * Examples:
+	 * - { nested: { value: "ok" } } (depth 2) => accepted
+	 * - { a: { b: { c: { d: { e: { f: { g: { h: { i: { j: { k: "too deep" } } } } } } } } } } }
+	 *   (depth 11) => throws "Maximum nesting depth (10) exceeded"
+	 */
 	describe('Deep Object Nesting', () => {
+		// Example: depth 5 => { nested: { nested: { nested: { nested: { nested: { value: "test" } } } } } }
 		fcTest.prop([fc.integer({ min: 1, max: 9 })], { numRuns: 20 })(
 			'accepts objects within depth limit',
 			async (depth) => {
@@ -649,6 +729,7 @@ describe('RequestBuilder - Property-Based Tests', () => {
 			},
 		);
 
+		// Example: 12 levels of nesting => throws error
 		test('rejects objects exceeding depth limit of 10', async () => {
 			const builder = new RequestBuilder(baseConfig);
 			let deepObject: Record<string, unknown> = { value: 'test' };
@@ -664,9 +745,18 @@ describe('RequestBuilder - Property-Based Tests', () => {
 		});
 	});
 
+	/**
+	 * Body Type Handling
+	 *
+	 * Examples:
+	 * - bodyType: "json" => Content-Type: application/json, body: '{"test":"value"}'
+	 * - bodyType: "form" => Content-Type: application/x-www-form-urlencoded, body: "test=value"
+	 * - bodyType: "multipart-form" => body is FormData instance
+	 */
 	describe('Body Type Handling', () => {
 		const bodyTypes = ['json', 'form', 'multipart-form'] as const;
 
+		// Example: buildFetchOptions({ test: "value" }) with bodyType "json" => valid options
 		fcTest.prop(
 			[
 				fc.constantFrom(...bodyTypes),

src/utils/array.test.ts

@@ -1,14 +1,29 @@
 import { fc, test as fcTest } from '@fast-check/vitest';
 import { toArray } from './array';
 
+/**
+ * Property-Based Tests for toArray utility
+ *
+ * These tests verify the function's behavior for ANY valid input,
+ * replacing example-based tests like:
+ *
+ * - toArray([1, 2, 3]) === [1, 2, 3] (same reference)
+ * - toArray("hello") === ["hello"]
+ * - toArray(42) === [42]
+ * - toArray({ key: "value" }) === [{ key: "value" }]
+ * - toArray(null) === []
+ * - toArray(undefined) === []
+ */
 describe('toArray - Property-Based Tests', () => {
+	// Example: toArray([1, 2, 3]) returns the exact same array instance, not a copy
 	fcTest.prop([fc.array(fc.anything())], { numRuns: 100 })(
 		'array input returns the same array reference',
 		(arr) => {
 			expect(toArray(arr)).toBe(arr);
 		},
 	);
 
+	// Example: toArray("hello") => ["hello"], toArray(42) => [42], toArray({a:1}) => [{a:1}]
 	fcTest.prop([fc.anything().filter((x) => !Array.isArray(x) && x != null)], { numRuns: 100 })(
 		'non-array non-nullish input returns single-element array',
 		(value) => {
@@ -18,13 +33,15 @@ describe('toArray - Property-Based Tests', () => {
 		},
 	);
 
+	// Example: toArray(null) => [], toArray(undefined) => []
 	fcTest.prop([fc.constantFrom(null, undefined)], { numRuns: 10 })(
 		'null or undefined returns empty array',
 		(value) => {
 			expect(toArray(value)).toEqual([]);
 		},
 	);
 
+	// Invariant: no matter what input, output is always an array
 	fcTest.prop([fc.anything()], { numRuns: 100 })('result is always an array', (value) => {
 		expect(Array.isArray(toArray(value))).toBe(true);
 	});

src/utils/tfidf-index.test.ts

@@ -81,6 +81,17 @@ describe('TF-IDF Index - Tool Name Scenarios', () => {
 	});
 });
 
+/**
+ * Property-Based Tests for TfidfIndex
+ *
+ * These tests verify invariants that must hold for ANY valid input,
+ * replacing the following example-based tests:
+ *
+ * - Score Validation: scores like 0.7071, 0.5, 1.0 are always in [0, 1]
+ * - Edge Cases: empty query "" returns [], query with no matches returns []
+ * - Case Sensitivity: "Alpha" and "ALPHA" and "alpha" return same results
+ * - Search Limits: search("term", 5) returns at most 5 results
+ */
 describe('TF-IDF Index - Property-Based Tests', () => {
 	const documentArbitrary = fc.record({
 		id: fc.string({ minLength: 1, maxLength: 20 }).filter((s) => s.trim().length > 0),
@@ -93,6 +104,7 @@ describe('TF-IDF Index - Property-Based Tests', () => {
 		.array(fc.stringMatching(/^[a-zA-Z][a-zA-Z0-9]*$/), { minLength: 1, maxLength: 5 })
 		.map((words) => words.join(' '));
 
+	// Example: search("alpha") on any corpus returns scores like 0.0, 0.5, 1.0 - never 1.5 or -0.1
 	fcTest.prop([corpusArbitrary, queryArbitrary], { numRuns: 100 })(
 		'scores are always within [0, 1] range',
 		(corpus, query) => {
@@ -107,6 +119,7 @@ describe('TF-IDF Index - Property-Based Tests', () => {
 		},
 	);
 
+	// Example: [{ score: 0.9 }, { score: 0.7 }, { score: 0.3 }] - always descending
 	fcTest.prop([corpusArbitrary, queryArbitrary], { numRuns: 100 })(
 		'results are always sorted by score in descending order',
 		(corpus, query) => {
@@ -120,6 +133,7 @@ describe('TF-IDF Index - Property-Based Tests', () => {
 		},
 	);
 
+	// Example: search("term", 3) with 10 matching docs returns only 3 results
 	fcTest.prop([corpusArbitrary, queryArbitrary, fc.integer({ min: 1, max: 50 })], { numRuns: 100 })(
 		'search returns at most k results',
 		(corpus, query, k) => {
@@ -131,6 +145,7 @@ describe('TF-IDF Index - Property-Based Tests', () => {
 		},
 	);
 
+	// Example: search("Alpha"), search("ALPHA"), search("alpha") all return identical results
 	fcTest.prop([corpusArbitrary, queryArbitrary], { numRuns: 100 })(
 		'search is case-insensitive',
 		(corpus, query) => {
@@ -148,6 +163,7 @@ describe('TF-IDF Index - Property-Based Tests', () => {
 		},
 	);
 
+	// Example: index.build([]) then search("anything") returns []
 	fcTest.prop([queryArbitrary], { numRuns: 50 })('empty corpus returns empty results', (query) => {
 		const index = new TfidfIndex();
 		index.build([]);
@@ -156,6 +172,7 @@ describe('TF-IDF Index - Property-Based Tests', () => {
 		expect(results).toHaveLength(0);
 	});
 
+	// Example: corpus has ids ["doc1", "doc2"], results only contain "doc1" or "doc2"
 	fcTest.prop([corpusArbitrary, queryArbitrary], { numRuns: 100 })(
 		'result IDs are from the indexed corpus',
 		(corpus, query) => {
@@ -170,6 +187,7 @@ describe('TF-IDF Index - Property-Based Tests', () => {
 		},
 	);
 
+	// Example: same corpus + same query always produces identical results
 	fcTest.prop([corpusArbitrary, queryArbitrary], { numRuns: 50 })(
 		'search is deterministic',
 		(corpus, query) => {