feat(json): add EditableJson base class with shared formatting utilities

Add a new EditableJson base class for generic JSON file manipulation
with formatting preservation, extracted from EditablePackageJson to
enable code reuse via composition pattern.

Key changes:
- Create EditableJson base class in src/json.ts
- Extract shared utilities to src/lib/json-format.ts
- Refactor EditableJson and EditablePackageJson to use shared utilities
- Add comprehensive test coverage (125 new tests)
- Export via package.json ./json module

refactor(json): reorganize into src/json/ directory structure

Reorganize JSON utilities to avoid lib/lib redundancy by creating a
dedicated src/json/ directory with modular subfiles.

Changes:
- Create src/json/ directory structure with submodules:
  - types.ts: Type definitions and interfaces
  - parse.ts: JSON parsing utilities (isJsonPrimitive, jsonParse)
  - format.ts: Formatting utilities (moved from lib/json-format.ts)
  - editable.ts: EditableJson class for file manipulation
  - index.ts: Barrel export for all JSON functionality
- Remove old src/json.ts file (replaced by modular structure)
- Update imports:
  - src/fs.ts: Import from json/types and json/parse
  - src/packages/editable.ts: Import from json/format
- Update package.json exports:
  - ./json → ./dist/json/index.js (main export)
  - ./json/editable, ./json/format, ./json/parse, ./json/types (submodule exports)
  - Remove ./lib/json-format export
- Move test file: test/unit/lib/json-format.test.ts → test/unit/json/format.test.ts
- All tests passing (224 tests in json module)

refactor(json): remove barrel file, use direct submodule exports

Remove the barrel index file to avoid redundant export patterns,
requiring direct imports from specific submodules instead.

Changes:
- Remove src/json/index.ts barrel file
- Remove ./json and ./json/index from package.json exports
- Update test imports to use direct submodule paths:
  - '@socketsecurity/lib/json/parse' for jsonParse and isJsonPrimitive
  - '@socketsecurity/lib/json/editable' for getEditableJsonClass
- All tests passing (224 tests)

Submodule exports available:
- @socketsecurity/lib/json/editable
- @socketsecurity/lib/json/format
- @socketsecurity/lib/json/parse
- @socketsecurity/lib/json/types

Author: jdalton

package.json

@@ -355,9 +355,21 @@
       "types": "./dist/ipc.d.ts",
       "default": "./dist/ipc.js"
     },
-    "./json": {
-      "types": "./dist/json.d.ts",
-      "default": "./dist/json.js"
+    "./json/editable": {
+      "types": "./dist/json/editable.d.ts",
+      "default": "./dist/json/editable.js"
+    },
+    "./json/format": {
+      "types": "./dist/json/format.d.ts",
+      "default": "./dist/json/format.js"
+    },
+    "./json/parse": {
+      "types": "./dist/json/parse.d.ts",
+      "default": "./dist/json/parse.js"
+    },
+    "./json/types": {
+      "types": "./dist/json/types.d.ts",
+      "default": "./dist/json/types.js"
     },
     "./lifecycle-script-names": {
       "types": "./dist/lifecycle-script-names.d.ts",

src/fs.ts

@@ -20,8 +20,8 @@ import { getAbortSignal } from './constants/process'
 import { isArray } from './arrays'
 import { deleteAsync, deleteSync } from './external/del'
 import { defaultIgnore, getGlobMatcher } from './globs'
-import type { JsonReviver } from './json'
-import { jsonParse } from './json'
+import type { JsonReviver } from './json/types'
+import { jsonParse } from './json/parse'
 import { objectFreeze, type Remap } from './objects'
 import { normalizePath, pathLikeToString } from './paths/normalize'
 import { registerCacheInvalidation } from './paths/rewire'

src/json/editable.ts

@@ -0,0 +1,279 @@
+/**
+ * @fileoverview Editable JSON file manipulation with formatting preservation.
+ */
+
+import {
+  INDENT_SYMBOL,
+  NEWLINE_SYMBOL,
+  detectIndent,
+  detectNewline,
+  getFormattingFromContent,
+  shouldSave as shouldSaveUtil,
+  sortKeys,
+  stringifyWithFormatting,
+  stripFormattingSymbols,
+} from './format'
+import type {
+  EditableJsonConstructor,
+  EditableJsonInstance,
+  EditableJsonOptions,
+  EditableJsonSaveOptions,
+} from './types'
+
+const identSymbol = INDENT_SYMBOL
+const newlineSymbol = NEWLINE_SYMBOL
+
+// IMPORTANT: Do not use destructuring here - use direct assignment instead.
+// tsgo has a bug that incorrectly transpiles destructured exports, resulting in
+// `exports.SomeName = void 0;` which causes runtime errors.
+// See: https://github.com/SocketDev/socket-packageurl-js/issues/3
+const JSONParse = JSON.parse
+
+let _EditableJsonClass: EditableJsonConstructor | undefined
+
+let _fs: typeof import('node:fs') | undefined
+/*@__NO_SIDE_EFFECTS__*/
+function getFs() {
+  if (_fs === undefined) {
+    // Use non-'node:' prefixed require to avoid Webpack errors.
+    _fs = /*@__PURE__*/ require('node:fs')
+  }
+  return _fs as typeof import('node:fs')
+}
+
+/**
+ * Parse JSON content and extract formatting metadata.
+ * @private
+ */
+function parseJson(content: string): unknown {
+  return JSONParse(content)
+}
+
+/**
+ * Read file content from disk.
+ * @private
+ */
+async function readFile(filepath: string): Promise<string> {
+  const { promises: fsPromises } = getFs()
+  return await fsPromises.readFile(filepath, 'utf8')
+}
+
+/**
+ * Get the EditableJson class for JSON file manipulation.
+ *
+ * @example
+ * ```ts
+ * import { getEditableJsonClass } from '@socketsecurity/lib/json'
+ *
+ * const EditableJson = getEditableJsonClass<MyConfigType>()
+ * const config = await EditableJson.load('./config.json')
+ * config.update({ someField: 'newValue' })
+ * await config.save({ sort: true })
+ * ```
+ */
+/*@__NO_SIDE_EFFECTS__*/
+export function getEditableJsonClass<
+  T = Record<string, unknown>,
+>(): EditableJsonConstructor<T> {
+  if (_EditableJsonClass === undefined) {
+    _EditableJsonClass = class EditableJson<T = Record<string, unknown>>
+      implements EditableJsonInstance<T>
+    {
+      _canSave = true
+      _content: T = {} as T
+      _path: string | undefined = undefined
+      _readFileContent = ''
+      _readFileJson: unknown = undefined
+
+      get content(): Readonly<T> {
+        return this._content
+      }
+
+      get filename(): string {
+        const path = this._path
+        if (!path) {
+          return ''
+        }
+        return path
+      }
+
+      get path(): string | undefined {
+        return this._path
+      }
+
+      static async create<T = Record<string, unknown>>(
+        path: string,
+        opts: EditableJsonOptions<T> = {},
+      ): Promise<EditableJsonInstance<T>> {
+        const instance = new EditableJson<T>()
+        instance.create(path)
+        return opts.data ? instance.update(opts.data) : instance
+      }
+
+      static async load<T = Record<string, unknown>>(
+        path: string,
+        opts: EditableJsonOptions<T> = {},
+      ): Promise<EditableJsonInstance<T>> {
+        const instance = new EditableJson<T>()
+        // Avoid try/catch if we aren't going to create
+        if (!opts.create) {
+          return await instance.load(path)
+        }
+        try {
+          return await instance.load(path)
+        } catch (err: unknown) {
+          if (
+            !(err as Error).message.includes('ENOENT') &&
+            !(err as Error).message.includes('no such file')
+          ) {
+            throw err
+          }
+          return instance.create(path)
+        }
+      }
+
+      create(path: string): this {
+        this._path = path
+        this._content = {} as T
+        this._canSave = true
+        return this
+      }
+
+      fromContent(data: unknown): this {
+        this._content = data as T
+        this._canSave = false
+        return this
+      }
+
+      fromJSON(data: string): this {
+        const parsed = parseJson(data) as T & Record<symbol, unknown>
+        // Extract and preserve formatting metadata
+        const indent = detectIndent(data)
+        const newline = detectNewline(data)
+
+        // Store formatting metadata using symbols
+        ;(parsed as Record<symbol, unknown>)[identSymbol] = indent
+        ;(parsed as Record<symbol, unknown>)[newlineSymbol] = newline
+
+        this._content = parsed as T
+        return this
+      }
+
+      async load(path: string, create?: boolean): Promise<this> {
+        this._path = path
+        let parseErr: unknown
+        try {
+          this._readFileContent = await readFile(this.filename)
+        } catch (err) {
+          if (!create) {
+            throw err
+          }
+          parseErr = err
+        }
+        if (parseErr) {
+          throw parseErr
+        }
+        this.fromJSON(this._readFileContent)
+        // Add AFTER fromJSON is called in case it errors.
+        this._readFileJson = parseJson(this._readFileContent)
+        return this
+      }
+
+      update(content: Partial<T>): this {
+        this._content = {
+          ...this._content,
+          ...content,
+        } as T
+        return this
+      }
+
+      async save(options?: EditableJsonSaveOptions): Promise<boolean> {
+        if (!this._canSave || this.content === undefined) {
+          throw new Error('No file path to save to')
+        }
+
+        // Check if save is needed
+        if (
+          !shouldSaveUtil(
+            this.content as Record<string | symbol, unknown>,
+            this._readFileJson as Record<string | symbol, unknown>,
+            this._readFileContent,
+            options,
+          )
+        ) {
+          return false
+        }
+
+        // Get content and formatting
+        const content = stripFormattingSymbols(
+          this.content as Record<string | symbol, unknown>,
+        )
+        const sortedContent = options?.sort ? sortKeys(content) : content
+        const formatting = getFormattingFromContent(
+          this.content as Record<string | symbol, unknown>,
+        )
+
+        // Generate file content
+        const fileContent = stringifyWithFormatting(sortedContent, formatting)
+
+        // Save to disk
+        const { promises: fsPromises } = getFs()
+        await fsPromises.writeFile(this.filename, fileContent)
+        this._readFileContent = fileContent
+        this._readFileJson = parseJson(fileContent)
+        return true
+      }
+
+      saveSync(options?: EditableJsonSaveOptions): boolean {
+        if (!this._canSave || this.content === undefined) {
+          throw new Error('No file path to save to')
+        }
+
+        // Check if save is needed
+        if (
+          !shouldSaveUtil(
+            this.content as Record<string | symbol, unknown>,
+            this._readFileJson as Record<string | symbol, unknown>,
+            this._readFileContent,
+            options,
+          )
+        ) {
+          return false
+        }
+
+        // Get content and formatting
+        const content = stripFormattingSymbols(
+          this.content as Record<string | symbol, unknown>,
+        )
+        const sortedContent = options?.sort ? sortKeys(content) : content
+        const formatting = getFormattingFromContent(
+          this.content as Record<string | symbol, unknown>,
+        )
+
+        // Generate file content
+        const fileContent = stringifyWithFormatting(sortedContent, formatting)
+
+        // Save to disk
+        const fs = getFs()
+        fs.writeFileSync(this.filename, fileContent)
+        this._readFileContent = fileContent
+        this._readFileJson = parseJson(fileContent)
+        return true
+      }
+
+      willSave(options?: EditableJsonSaveOptions): boolean {
+        if (!this._canSave || this.content === undefined) {
+          return false
+        }
+
+        return shouldSaveUtil(
+          this.content as Record<string | symbol, unknown>,
+          this._readFileJson as Record<string | symbol, unknown>,
+          this._readFileContent,
+          options,
+        )
+      }
+    } as EditableJsonConstructor
+  }
+  return _EditableJsonClass as EditableJsonConstructor<T>
+}