/**
 * # JsonUtilities - Comment-Preserving JSON Handling
 *
 * This module provides centralized utilities for parsing and stringifying JSON
 * while preserving C-style comments (// and /* *\/).
 *
 * ## Key Concepts
 *
 * - Uses the `comment-json` library which stores comments as Symbol properties
 * - Comments are attached to the parsed object and survive mutations
 * - To preserve comments during round-trip, you must:
 *   1. Parse once with `parseJsonWithComments()`
 *   2. Mutate the returned object (don't create a new one)
 *   3. Stringify with `stringifyJsonWithComments()`
 *
 * ## Important Limitations
 *
 * - Array reassignment loses comments - use `commentJson.assign()` or in-place mutations
 * - Copying objects with spread/Object.assign loses comment symbols
 * - The parsed object must be retained to preserve comments
 *
 * ## Usage Pattern
 *
 * ```typescript
 * // Parse and cache the result
 * const obj = JsonUtilities.parseJsonWithComments(jsonString);
 *
 * // Modify properties directly on the parsed object
 * obj.someProperty = "new value";
 *
 * // Stringify preserves comments
 * const output = JsonUtilities.stringifyJsonWithComments(obj);
 * ```
 */
import * as commentJson from "comment-json";
export type { CommentJSONValue, CommentObject, CommentToken } from "comment-json";
export declare const CommentArrayClass: typeof commentJson.CommentArray;
/**
 * Parses a JSON string while preserving comments.
 * The returned object contains Symbol properties that store comment metadata.
 *
 * @param jsonString The JSON string to parse (may contain // and /* *\/ comments)
 * @param fixContent If true, applies Utilities.fixJsonContentForCommentJson to handle
 *                   trailing commas and other non-standard JSON before parsing
 * @returns The parsed object with comment metadata preserved as Symbol properties
 */
export declare function parseJsonWithComments(jsonString: string, fixContent?: boolean): commentJson.CommentJSONValue;
/**
 * Stringifies an object to JSON, preserving any comments stored as Symbol properties.
 *
 * @param value The object to stringify (should be one returned from parseJsonWithComments
 *              or created with comment-json utilities to have comments)
 * @param space Indentation (default: 2 spaces)
 * @returns JSON string with comments restored in their original positions
 */
export declare function stringifyJsonWithComments(value: unknown, space?: string | number): string;
/**
 * Assigns properties from source to target while preserving comment metadata.
 * Use this instead of Object.assign or spread to maintain comments.
 *
 * @param target The target object to assign properties to
 * @param source The source object to copy properties from
 * @param keys Optional array of keys to assign. If not provided, all keys are assigned.
 * @returns The target object with properties and comments from source
 */
export declare function assignJsonPreservingComments<T, S>(target: T, source: S, keys?: readonly (string | number)[]): T;
/**
 * Checks if two JSON strings are semantically equal (same data, ignoring whitespace/formatting).
 * This does NOT consider comments - it only compares the actual data values.
 *
 * @param contentA First JSON string
 * @param contentB Second JSON string
 * @returns true if the JSON data is semantically equivalent
 */
export declare function jsonContentsSemanticallyEqual(contentA: string, contentB: string): boolean;
/**
 * Compares two JSON objects for semantic equality, ignoring comment metadata.
 * Use this when you have already-parsed objects and want to check if their
 * actual data (not comments) is the same.
 *
 * @param objA First object (may have comment metadata)
 * @param objB Second object (may have comment metadata)
 * @returns true if the JSON data is semantically equivalent
 */
export declare function jsonObjectsSemanticallyEqual(objA: unknown, objB: unknown): boolean;
/**
 * Merges new values into an existing comment-json object, preserving comments.
 * This is the recommended way to update a JSON object while keeping its comments.
 *
 * @param original The original parsed object with comments
 * @param updates An object containing the properties to update
 * @returns The original object with updates applied (mutates in place)
 */
export declare function mergeJsonPreservingComments<T extends object>(original: T, updates: Partial<T>): T;
/**
 * Creates a deep clone of a comment-json object, preserving comments.
 * Use this when you need a copy that retains comment metadata.
 *
 * @param obj The object to clone
 * @returns A new object with the same data and comments
 */
export declare function cloneJsonWithComments<T>(obj: T): T;
/**
 * Checks if an object was parsed with comment-json and contains comment metadata.
 *
 * @param obj The object to check
 * @returns true if the object has comment Symbol properties
 */
export declare function hasCommentMetadata(obj: unknown): boolean;
/**
 * Default export providing all JsonUtilities functions as a namespace-like object.
 * This allows both `import JsonUtilities from "./JsonUtilities"` and
 * `import { parseJsonWithComments } from "./JsonUtilities"` usage patterns.
 */
declare const JsonUtilities: {
    parseJsonWithComments: typeof parseJsonWithComments;
    stringifyJsonWithComments: typeof stringifyJsonWithComments;
    assignJsonPreservingComments: typeof assignJsonPreservingComments;
    mergeJsonPreservingComments: typeof mergeJsonPreservingComments;
    jsonContentsSemanticallyEqual: typeof jsonContentsSemanticallyEqual;
    jsonObjectsSemanticallyEqual: typeof jsonObjectsSemanticallyEqual;
    cloneJsonWithComments: typeof cloneJsonWithComments;
    hasCommentMetadata: typeof hasCommentMetadata;
    CommentArrayClass: typeof commentJson.CommentArray;
};
export default JsonUtilities;