fix: Fix Cl.parse and Cl.stringify to match JSON.parse and JSON.stringify in escaping characters and string handling

Author: janniks

packages/transactions/src/clarity/parser.ts

@@ -1,4 +1,4 @@
-import { Cl, ClarityValue, TupleCV } from '..';
+import { Cl, ClarityValue, ListCV, TupleCV } from '..';
 
 // COMBINATOR TYPES
 type Combinator = (str: string) => ParseResult;
@@ -193,7 +193,17 @@ function clBuffer(): Combinator {
 
 /** @ignore helper for string values, removes escaping and unescapes special characters */
 function unescape(input: string): string {
-  return input.replace(/\\\\/g, '\\').replace(/\\(.)/g, '$1');
+  // To correctly unescape sequences like \n, \t, \", \\, \uXXXX, etc.,
+  // we can leverage JSON.parse by wrapping the input string in double quotes.
+  // This ensures that all standard JSON escape sequences are handled according
+  // to the JSON specification, aligning with the test cases provided.
+  try {
+    return JSON.parse(`"${input}"`);
+  } catch (error) {
+    throw new Error(
+      `Failed to unescape string: "${input}" ${error instanceof Error ? error.message : error}`
+    );
+  }
 }
 
 function clAscii(): Combinator {

packages/transactions/src/clarity/prettyPrint.ts

@@ -8,6 +8,12 @@
 
 import { ClarityType, ClarityValue, ListCV, TupleCV } from '.';
 
+function escape(value: string): string {
+  // Use JSON.stringify to handle all necessary escape sequences (e.g., \n, \r, \t, \", \\, \uXXXX).
+  // JSON.stringify(value) produces a string like "\"hello\nworld\"", so we slice off the leading and trailing quotes.
+  return JSON.stringify(value).slice(1, -1);
+}
+
 function formatSpace(space: number, depth: number, end = false) {
   if (!space) return ' ';
   return `\n${' '.repeat(space * (depth - (end ? 1 : 0)))}`;
@@ -80,8 +86,8 @@ function prettyPrintWithDepth(cv: ClarityValue, space = 0, depth: number): strin
   if (cv.type === ClarityType.Int) return cv.value.toString();
   if (cv.type === ClarityType.UInt) return `u${cv.value.toString()}`;
 
-  if (cv.type === ClarityType.StringASCII) return `"${cv.value}"`;
-  if (cv.type === ClarityType.StringUTF8) return `u"${cv.value}"`;
+  if (cv.type === ClarityType.StringASCII) return `"${escape(cv.value)}"`;
+  if (cv.type === ClarityType.StringUTF8) return `u"${escape(cv.value)}"`;
 
   if (cv.type === ClarityType.PrincipalContract) return `'${cv.value}`;
   if (cv.type === ClarityType.PrincipalStandard) return `'${cv.value}`;

packages/transactions/tests/clarity.test.ts

@@ -792,6 +792,8 @@ const TEST_CASES_PARSER = [
   { input: '"hello world"', expected: Cl.stringAscii('hello world') },
   { input: 'u"hello world"', expected: Cl.stringUtf8('hello world') },
   { input: '"hello \\"world\\""', expected: Cl.stringAscii('hello "world"') },
+  { input: '"hello \\\\"', expected: Cl.stringAscii('hello \\') },
+  { input: '"hello \\\\\\", \\"world\\""', expected: Cl.stringAscii('hello \\", "world"') },
   { input: '(list 1 2 3)', expected: Cl.list([Cl.int(1), Cl.int(2), Cl.int(3)]) },
   { input: '( list  1   2    3 )', expected: Cl.list([Cl.int(1), Cl.int(2), Cl.int(3)]) },
   { input: '( list )', expected: Cl.list([]) },
@@ -830,11 +832,58 @@ const TEST_CASES_PARSER = [
       ])
     ),
   },
+  { input: 'u""', expected: Cl.stringUtf8('') },
+  { input: 'u"\\\\"', expected: Cl.stringUtf8('\\') },
+  { input: `u"\\n"`, expected: Cl.stringUtf8('\n') },
 ] as const;
 
-test.each(TEST_CASES_PARSER)('clarity parser %p', ({ input, expected }) => {
-  const result = parse(input);
-  expect(result).toEqual(expected);
+const TEST_CASES_PARSER_INVERTIBLE = [
+  { input: '""', expected: Cl.stringAscii('') },
+  { input: '"hello"', expected: Cl.stringAscii('hello') },
+  { input: '"\\"hello\\""', expected: Cl.stringAscii('"hello"') },
+  { input: '"a\\\\b"', expected: Cl.stringAscii('a\\b') },
+  { input: 'u"a\\\\\\\\b"', expected: Cl.stringUtf8('a\\\\b') },
+  { input: 'u"a\\"b"', expected: Cl.stringUtf8('a"b') },
+  { input: 'u"こんにちは"', expected: Cl.stringUtf8('こんにちは') },
+
+  { input: '"\\\\path\\\\to\\\\file"', expected: Cl.stringAscii('\\path\\to\\file') },
+  { input: '"\\b\\f\\n\\r\\t\\"\\\\"', expected: Cl.stringAscii('\b\f\n\r\t"\\') },
+
+  {
+    input: '"Line1\\nLine2\\u0002 \\"Quote\\" \\\\ slash"',
+    expected: Cl.stringAscii('Line1\nLine2\u0002 "Quote" \\ slash'),
+  },
+
+  { input: 'u"résumé – ångström"', expected: Cl.stringUtf8('résumé – ångström') },
+] as const;
+
+test.each([...TEST_CASES_PARSER, ...TEST_CASES_PARSER_INVERTIBLE])(
+  'clarity parser %p',
+  ({ input, expected }) => {
+    const result = parse(input);
+    expect(result).toEqual(expected);
+  }
+);
+
+test.each(TEST_CASES_PARSER_INVERTIBLE)('clarity parser inverseable %p', ({ input, expected }) => {
+  const parsed = parse(input);
+  expect(parsed).toEqual(expected);
+
+  const stringified = Cl.stringify(parsed);
+  expect(stringified).toEqual(input);
 });
 
+test.each(TEST_CASES_PARSER_INVERTIBLE)(
+  'clarity parser string handling matches JSON JS implementation %p',
+  ({ input, expected }) => {
+    if (expected.type !== 'utf8' && expected.type !== 'ascii') return; // Only strings
+    if (expected.type === 'utf8') input = input.replace('u"', '"') as any; // Remove the u" prefix for UTF-8 strings
+
+    // String handling in Cl.parse/Cl.stringify should match the JSON.parse/JSON.stringify implementation
+    const parsed = JSON.parse(input);
+    const stringified = JSON.stringify(parsed);
+    expect(stringified).toEqual(input);
+  }
+);
+
 // const TEST_CASES_PARSER_THROW = []; // todo: e.g. `{}`