AG-21246 Enhance logging in 'trusted-json-set'

Squashed commit of the following:

commit d3c03ef
Author: Adam Wróblewski <adam@adguard.com>
Date:   Mon Apr 13 13:29:14 2026 +0200

    Fix logging with stack

commit db9a719
Author: Adam Wróblewski <adam@adguard.com>
Date:   Sat Apr 11 20:47:07 2026 +0200

    Enhance 'trusted-json-set' and related utilities — support logging-only mode, JSONPath matching, and mutation callbacks

commit ff1032a
Author: Adam Wróblewski <adam@adguard.com>
Date:   Fri Apr 10 14:04:50 2026 +0200

    Update changelog

commit 734ca09
Author: Adam Wróblewski <adam@adguard.com>
Date:   Fri Apr 10 12:59:20 2026 +0200

    Enhance logging in 'trusted-json-set' — add structured cloning support and improve debug messages

Author: AdamWr

CHANGELOG.md

@@ -23,11 +23,15 @@ The format is based on [Keep a Changelog], and this project adheres to [Semantic
 
 ### Changed
 
+- `trusted-json-set` now supports method-only logging, filtered log-only output,
+  JSONPath-based log-only filters, and verbose logs only when a write actually happens [#308].
 - `log-addEventListener` scriptlet: added new optional `noProtect` parameter,
   improving compatibility with other scriptlets that need to override `addEventListener` [#551].
 
 ### Fixed
 
+- Logging original object in `trusted-json-set` scriptlet, previously original and modified object were pointing
+  to the same reference, so the same content was logged, now deep copy is created for original object [#308].
 - `trusted-click-element` no longer throws when event handlers set `cancelBubble`
   on spoofed events [#555].
 

src/helpers/json-path-utils.ts

@@ -243,6 +243,7 @@ export function buildJsonPathExpression(selectorPath: string, argumentValue: any
  * @param nativeObjects optional bag of native object references
  * @param onMutation optional callback fired once if any mutation happens
  * @param stack optional stack trace pattern that must match for processing to occur
+ * @param matchOnly when true, evaluates guards and selector matches without mutating `root`
  * @returns mutated root value
  */
 export const jsonPath = (
@@ -252,6 +253,7 @@ export const jsonPath = (
     nativeObjects: JsonPathNativeObjects,
     onMutation?: JsonPathMutationObserver,
     stack = '',
+    matchOnly = false,
 ): any => {
     const ROOT_PATH = '$';
     const DOT = '.';
@@ -1769,12 +1771,19 @@ export const jsonPath = (
             }
         }
 
+        const matches = evaluateSelector(root, command.selector);
+        if (matchOnly) {
+            if (matches.length > 0 && onMutation) {
+                onMutation();
+            }
+            return root;
+        }
+
         if (!isMutationAllowed(command.mutation.mode)) {
             logMessage(source, 'JSONPath set and append operations are allowed only in trusted scriptlets');
             return root;
         }
 
-        const matches = evaluateSelector(root, command.selector);
         if (command.mutation.mode === 'remove') {
             removeMatches(matches);
             if (didMutate && onMutation) {
@@ -1795,3 +1804,44 @@ export const jsonPath = (
 
     return root;
 };
+
+/**
+ * Checks whether a JSON value matches a JSONPath selector without mutating it.
+ *
+ * Supports the same selector syntax and leading guards as `jsonPath`, but only
+ * reports whether the selector matched at least one candidate.
+ *
+ * @param source source descriptor used for logging and parsing
+ * @param root JSON object or array to inspect
+ * @param path JSONPath expression used for matching
+ * @param nativeObjects optional bag of native object references
+ * @param stack optional stack trace pattern that must match for processing to occur
+ * @returns true when the expression matches the input value
+ */
+export const matchesJsonPath = (
+    source: Source,
+    root: Record<string, any>,
+    path: string,
+    nativeObjects: JsonPathNativeObjects,
+    stack = '',
+): boolean => {
+    if (!path) {
+        return true;
+    }
+
+    let didMatch = false;
+
+    jsonPath(
+        source,
+        root,
+        path,
+        nativeObjects,
+        () => {
+            didMatch = true;
+        },
+        stack,
+        true,
+    );
+
+    return didMatch;
+};

src/helpers/log-message.ts

@@ -33,7 +33,11 @@ export const logMessage = (
         // Template literals convert object to string,
         // so 'message' should not be passed to template literals
         // as it will not be logged correctly
-        nativeConsole(`${name}:`, message);
+        if (Array.isArray(message)) {
+            nativeConsole(`${name}:`, ...message);
+        } else {
+            nativeConsole(`${name}:`, message);
+        }
         return;
     }
 

src/helpers/prune-utils.ts

@@ -199,6 +199,7 @@ export const jsonPruner = (
  * @param requiredPaths array of required property chains that must all be present for the set to occur
  * @param stack string which should be matched by stack trace
  * @param nativeObjects reference to native objects
+ * @param onMutation optional callback fired after each successful write
  * @returns the modified root object
  */
 export const jsonSetter = (
@@ -210,9 +211,17 @@ export const jsonSetter = (
     requiredPaths: { path: string; value?: any }[],
     stack: string,
     nativeObjects: any,
+    onMutation?: () => void,
 ): ArbitraryObject => {
     const { nativeStringify } = nativeObjects;
 
+    const notifyMutation = () => {
+        hit(source);
+        if (onMutation) {
+            onMutation();
+        }
+    };
+
     if (!setPath) {
         logMessage(
             source,
@@ -243,7 +252,7 @@ export const jsonSetter = (
                 const node = matchedNodes[i];
                 if (node && node.base) {
                     node.base[node.prop] = getValue(node.base[node.prop]);
-                    hit(source);
+                    notifyMutation();
                 }
             }
         } else if (!hasWildcard && valueFilter === undefined) {
@@ -264,7 +273,7 @@ export const jsonSetter = (
             }
             const lastPart = pathParts[pathParts.length - 1];
             current[lastPart] = getValue(current[lastPart]);
-            hit(source);
+            notifyMutation();
         }
     } catch (e) {
         logMessage(source, e);