refactor: consolidate JSON parsing under @socketsecurity/lib/json

Remove the `./validation/*` subpath — all JSON parsing now lives
under `@socketsecurity/lib/json`. The former split meant callers
had to choose between two sibling modules with overlapping
purpose:

- `@socketsecurity/lib/json/parse` (trusted-source `jsonParse` with
  Buffer/BOM/filepath-aware errors)
- `@socketsecurity/lib/validation/json-parser` (untrusted-source
  `safeJsonParse` with prototype-pollution reviver + size limits
  + Zod schema hook)

Merged by moving `safeJsonParse` into `src/json/parse.ts` as a
sibling to `jsonParse`. The schema-validation branch now delegates
to `validateSchema` from `@socketsecurity/lib/schema/validate`
instead of hand-normalizing Zod error shapes, so the
path/message-join logic lives in exactly one place.

Changes:
- `src/json/parse.ts` — add `safeJsonParse` (alphabetical order
  after `jsonParse`), including `prototypePollutionReviver` and
  `DANGEROUS_KEYS`. Imports `validateSchema` + `Schema<T>` from
  the `schema/*` module.
- `src/json/types.ts` — add `SafeJsonParseOptions` (was in
  `validation/types.ts`).
- `test/unit/validation/json-parser.test.mts` renamed to
  `test/unit/json/safe-parse.test.mts` with updated import path
  and describe name. All 24 tests still pass unchanged.
- Delete `src/validation/json-parser.ts`, `src/validation/types.ts`,
  and both empty parent dirs. `Schema` + `ParseResult` types in
  the old `validation/types.ts` are superseded by
  `schema/types.ts`.
- `package.json` + `docs/api-index.md` — regenerated; the
  `./validation/*` exports are gone.

Consumers migrating: change
  import { safeJsonParse } from '@socketsecurity/lib/validation/json-parser'
to
  import { safeJsonParse } from '@socketsecurity/lib/json/parse'
The function signature is identical.

Author: jdalton

docs/api-index.md

@@ -5,7 +5,7 @@ Each entry links to the source module and shows the first sentence of its `@file
 
 > Regenerate with `node scripts/fix/generate-api-index.mts` after adding or removing exports. Do not edit this file by hand.
 
-**Jump to:** [Top-level](#top-level) · [argv/](#argv) · [constants/](#constants) · [cover/](#cover) · [dlx/](#dlx) · [effects/](#effects) · [env/](#env) · [json/](#json) · [packages/](#packages) · [paths/](#paths) · [releases/](#releases) · [schema/](#schema) · [stdio/](#stdio) · [themes/](#themes) · [validation/](#validation)
+**Jump to:** [Top-level](#top-level) · [argv/](#argv) · [constants/](#constants) · [cover/](#cover) · [dlx/](#dlx) · [effects/](#effects) · [env/](#env) · [json/](#json) · [packages/](#packages) · [paths/](#paths) · [releases/](#releases) · [schema/](#schema) · [stdio/](#stdio) · [themes/](#themes)
 
 ## Top-level
 
@@ -222,10 +222,3 @@ Each entry links to the source module and shows the first sentence of its `@file
 | [`@socketsecurity/lib/themes/themes`](../src/themes/themes.ts)   | Elegant theme definitions for Socket libraries.     |
 | [`@socketsecurity/lib/themes/types`](../src/themes/types.ts)     | Elegant theme type system.                          |
 | [`@socketsecurity/lib/themes/utils`](../src/themes/utils.ts)     | Theme utilities — color resolution and composition. |
-
-## validation/
-
-| Subpath                                                                          | Description                                              |
-| -------------------------------------------------------------------------------- | -------------------------------------------------------- |
-| [`@socketsecurity/lib/validation/json-parser`](../src/validation/json-parser.ts) | Safe JSON parsing with validation and security controls. |
-| [`@socketsecurity/lib/validation/types`](../src/validation/types.ts)             | Validation type definitions.                             |

package.json

@@ -667,14 +667,6 @@
       "types": "./dist/url.d.ts",
       "default": "./dist/url.js"
     },
-    "./validation/json-parser": {
-      "types": "./dist/validation/json-parser.d.ts",
-      "default": "./dist/validation/json-parser.js"
-    },
-    "./validation/types": {
-      "types": "./dist/validation/types.d.ts",
-      "default": "./dist/validation/types.js"
-    },
     "./versions": {
       "types": "./dist/versions.d.ts",
       "default": "./dist/versions.js"

src/json/parse.ts

@@ -1,10 +1,19 @@
 /**
  * @fileoverview JSON parsing utilities with Buffer detection and BOM stripping.
- * Provides safe JSON parsing with automatic encoding handling.
+ * Provides safe JSON parsing with automatic encoding handling, plus
+ * `safeJsonParse` for untrusted input (prototype-pollution protection +
+ * size limits + optional schema validation).
  */
 
+import { validateSchema } from '../schema/validate'
 import { stripBom } from '../strings'
-import type { JsonParseOptions, JsonPrimitive, JsonValue } from './types'
+import type { Schema } from '../schema/types'
+import type {
+  JsonParseOptions,
+  JsonPrimitive,
+  JsonValue,
+  SafeJsonParseOptions,
+} from './types'
 
 // IMPORTANT: Do not use destructuring here - use direct assignment instead.
 // tsgo has a bug that incorrectly transpiles destructured exports, resulting in
@@ -157,3 +166,106 @@ export function jsonParse(
   }
   return undefined
 }
+
+const DANGEROUS_KEYS = new Set(['__proto__', 'constructor', 'prototype'])
+
+/**
+ * JSON.parse reviver that rejects prototype pollution keys at any depth.
+ *
+ * @internal
+ */
+function prototypePollutionReviver(key: string, value: unknown): unknown {
+  if (DANGEROUS_KEYS.has(key)) {
+    throw new Error(
+      'JSON contains potentially malicious prototype pollution keys',
+    )
+  }
+  return value
+}
+
+const DEFAULT_MAX_SIZE = 10 * 1024 * 1024
+
+/**
+ * Safely parse JSON with optional schema validation and security controls.
+ * Throws on parse failure, validation failure, or security violation.
+ *
+ * Recommended for parsing untrusted JSON (user input, network payloads,
+ * anything beyond a trust boundary). Layers:
+ * 1. Size cap (default 10 MB) prevents memory exhaustion.
+ * 2. Prototype-pollution reviver rejects `__proto__` / `constructor` /
+ *    `prototype` keys at any depth (unless `allowPrototype: true`).
+ * 3. Optional Zod-shaped schema validation via
+ *    `@socketsecurity/lib/schema/validate`.
+ *
+ * For trusted-source reads (package.json, local config files), prefer
+ * `jsonParse()` — it offers Buffer/BOM handling and filepath-aware error
+ * messages, without the untrusted-input overhead.
+ *
+ * @throws {Error} When `jsonString` exceeds `maxSize`.
+ * @throws {Error} When JSON parsing fails.
+ * @throws {Error} When prototype-pollution keys are detected (and
+ *   `allowPrototype` is not `true`).
+ * @throws {Error} When schema validation fails.
+ *
+ * @example
+ * ```ts
+ * // Basic parsing with type inference.
+ * const data = safeJsonParse<User>('{"name":"Alice","age":30}')
+ *
+ * // With schema validation.
+ * import { z } from 'zod'
+ * const userSchema = z.object({ name: z.string(), age: z.number() })
+ * const user = safeJsonParse('{"name":"Alice","age":30}', userSchema)
+ *
+ * // With size limit.
+ * const data = safeJsonParse(jsonString, undefined, { maxSize: 1024 })
+ *
+ * // Allow prototype keys (DANGEROUS — only for trusted sources).
+ * const data = safeJsonParse('{"__proto__":{}}', undefined, {
+ *   allowPrototype: true,
+ * })
+ * ```
+ */
+/*@__NO_SIDE_EFFECTS__*/
+export function safeJsonParse<T = unknown>(
+  jsonString: string,
+  schema?: Schema<T> | undefined,
+  options: SafeJsonParseOptions = {},
+): T {
+  const { allowPrototype = false, maxSize = DEFAULT_MAX_SIZE } = options
+
+  // Size check up front.
+  const byteLength = Buffer.byteLength(jsonString, 'utf8')
+  if (byteLength > maxSize) {
+    throw new Error(
+      `JSON string exceeds maximum size limit${
+        maxSize !== DEFAULT_MAX_SIZE ? ` of ${maxSize} bytes` : ''
+      }`,
+    )
+  }
+
+  // Parse with the prototype-pollution reviver unless the caller opted out.
+  let parsed: unknown
+  try {
+    parsed = allowPrototype
+      ? JSONParse(jsonString)
+      : JSONParse(jsonString, prototypePollutionReviver)
+  } catch (error) {
+    throw new Error(`Failed to parse JSON: ${error}`)
+  }
+
+  // Optional schema validation — route through validateSchema so the
+  // normalization logic lives in exactly one place.
+  if (schema) {
+    const result = validateSchema(schema, parsed)
+    if (!result.ok) {
+      const summary = result.errors
+        .map(e => `${e.path.join('.') || '(root)'}: ${e.message}`)
+        .join(', ')
+      throw new Error(`Validation failed: ${summary}`)
+    }
+    return result.value
+  }
+
+  return parsed as T
+}

src/json/types.ts

@@ -77,6 +77,57 @@ export type JsonValue = JsonPrimitive | JsonObject | JsonArray
  */
 export type JsonReviver = (key: string, value: unknown) => unknown
 
+/**
+ * Options for `safeJsonParse`: security controls for untrusted JSON.
+ *
+ * Distinct from `JsonParseOptions` (which is scoped to reviver /
+ * error-handling for trusted-source fs reads). Use this type when
+ * parsing user input, network payloads, or anything beyond a trust
+ * boundary.
+ *
+ * @example
+ * ```ts
+ * const options: SafeJsonParseOptions = {
+ *   maxSize: 1024 * 1024, // 1MB limit
+ *   allowPrototype: false // Block prototype pollution
+ * }
+ * ```
+ */
+export interface SafeJsonParseOptions {
+  /**
+   * Allow dangerous prototype pollution keys (`__proto__`, `constructor`, `prototype`).
+   * Set to `true` only if you trust the JSON source completely.
+   *
+   * @default false
+   *
+   * @example
+   * ```ts
+   * // Will throw error by default
+   * safeJsonParse('{"__proto__": {"polluted": true}}')
+   *
+   * // Allows the parse (dangerous!)
+   * safeJsonParse('{"__proto__": {"polluted": true}}', undefined, {
+   *   allowPrototype: true
+   * })
+   * ```
+   */
+  allowPrototype?: boolean | undefined
+
+  /**
+   * Maximum allowed size of JSON string in bytes.
+   * Prevents memory exhaustion from extremely large payloads.
+   *
+   * @default 10_485_760 (10 MB)
+   *
+   * @example
+   * ```ts
+   * // Limit to 1KB
+   * safeJsonParse(jsonString, undefined, { maxSize: 1024 })
+   * ```
+   */
+  maxSize?: number | undefined
+}
+
 /**
  * Options for JSON parsing operations.
  */