@typia/utils 12.0.0-dev.20260225

package/lib/utils/stringifyValidationFailure.js

@@ -0,0 +1,326 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.stringifyValidationFailure = stringifyValidationFailure;
+const NamingConvention_1 = require("./NamingConvention");
+const dedent_1 = require("./dedent");
+/**
+ * Format validation failure for LLM auto-correction feedback.
+ *
+ * When LLM generates invalid function call arguments, this produces annotated
+ * JSON with inline `// ❌` error comments at each invalid property. The output
+ * is wrapped in a markdown code block so that LLM can understand and correct
+ * its mistakes in the next turn.
+ *
+ * Below is an example of the output format:
+ *
+ * ```json
+ * {
+ *   "name": "John",
+ *   "age": "twenty", // ❌ [{"path":"$input.age","expected":"number & Type<\"uint32\">"}]
+ *   "email": "not-an-email", // ❌ [{"path":"$input.email","expected":"string & Format<\"email\">"}]
+ *   "hobbies": "reading" // ❌ [{"path":"$input.hobbies","expected":"Array<string>"}]
+ * }
+ * ```
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ * @param failure Validation failure from {@link ILlmFunction.validate}
+ * @returns Markdown code block with error-annotated JSON
+ */
+function stringifyValidationFailure(failure) {
+    const usedErrors = new Set();
+    const jsonOutput = stringify({
+        value: failure.data,
+        errors: failure.errors,
+        path: "$input",
+        tab: 0,
+        inArray: false,
+        inToJson: false,
+        usedErrors,
+    });
+    // Find errors that couldn't be embedded
+    const unmappableErrors = failure.errors.filter((e) => !usedErrors.has(e));
+    // If there are unmappable errors, append them as a separate block
+    if (unmappableErrors.length > 0)
+        return (0, dedent_1.dedent) `
+      \`\`\`json
+      ${jsonOutput}
+      \`\`\`
+
+      **Unmappable validation errors:**
+      \`\`\`json
+      ${JSON.stringify(unmappableErrors, null, 2)}
+      \`\`\`
+    `;
+    return (0, dedent_1.dedent) `
+    \`\`\`json
+    ${jsonOutput}
+    \`\`\`
+  `;
+}
+function stringify(props) {
+    var _a;
+    const { value, errors, path, tab, inArray, inToJson, usedErrors } = props;
+    const indent = "  ".repeat(tab);
+    const errorComment = getErrorComment(path, errors, usedErrors);
+    // Handle undefined in arrays
+    if (inArray && value === undefined) {
+        return `${indent}undefined${errorComment}`;
+    }
+    // Array
+    if (Array.isArray(value)) {
+        // Check for missing array element errors (path[])
+        const missingElementErrors = getMissingArrayElementErrors(path, errors, usedErrors);
+        const hasMissingElements = missingElementErrors.length > 0;
+        if (value.length === 0) {
+            // Empty array but has missing element errors - show placeholders
+            if (hasMissingElements) {
+                const innerIndent = "  ".repeat(tab + 1);
+                const lines = [];
+                lines.push(`${indent}[${errorComment}`);
+                missingElementErrors.forEach((e, idx) => {
+                    const errComment = ` // ❌ ${JSON.stringify([{ path: e.path, expected: e.expected, description: e.description }])}`;
+                    const comma = idx < missingElementErrors.length - 1 ? "," : "";
+                    lines.push(`${innerIndent}undefined${comma}${errComment}`);
+                });
+                lines.push(`${indent}]`);
+                return lines.join("\n");
+            }
+            return `${indent}[]${errorComment}`;
+        }
+        const lines = [];
+        lines.push(`${indent}[${errorComment}`);
+        value.forEach((item, index) => {
+            const itemPath = `${path}[${index}]`;
+            const isLastElement = index === value.length - 1;
+            // If there are missing element errors, this is not truly the last line
+            const needsComma = !isLastElement || hasMissingElements;
+            let itemStr = stringify({
+                value: item,
+                errors,
+                path: itemPath,
+                tab: tab + 1,
+                inArray: true,
+                inToJson: false,
+                usedErrors,
+            });
+            // Add comma before the error comment if not the last element
+            if (needsComma) {
+                const itemLines = itemStr.split("\n");
+                const lastLine = itemLines[itemLines.length - 1];
+                const commentIndex = lastLine.indexOf(" //");
+                if (commentIndex !== -1) {
+                    itemLines[itemLines.length - 1] = `${lastLine.slice(0, commentIndex)},${lastLine.slice(commentIndex)}`;
+                }
+                else {
+                    itemLines[itemLines.length - 1] += ",";
+                }
+                itemStr = itemLines.join("\n");
+            }
+            lines.push(itemStr);
+        });
+        // Add missing element placeholders at the end for each [] error
+        if (hasMissingElements) {
+            const innerIndent = "  ".repeat(tab + 1);
+            missingElementErrors.forEach((e, idx) => {
+                const errComment = ` // ❌ ${JSON.stringify([{ path: e.path, expected: e.expected, description: e.description }])}`;
+                const comma = idx < missingElementErrors.length - 1 ? "," : "";
+                lines.push(`${innerIndent}undefined${comma}${errComment}`);
+            });
+        }
+        lines.push(`${indent}]`);
+        return lines.join("\n");
+    }
+    // Object
+    if (typeof value === "object" && value !== null) {
+        // Check for toJSON method
+        // biome-ignore lint: intended
+        if (!inToJson && typeof value.toJSON === "function") {
+            // biome-ignore lint: intended
+            const jsonValue = value.toJSON();
+            return stringify({
+                value: jsonValue,
+                errors,
+                path,
+                tab,
+                inArray,
+                inToJson: true,
+                usedErrors,
+            });
+        }
+        // Get all entries from the object (including undefined values that have errors)
+        const allEntries = Object.entries(value);
+        // Split into defined and undefined entries
+        const definedEntries = allEntries.filter(([_, val]) => val !== undefined);
+        const undefinedEntryKeys = new Set(allEntries.filter(([_, val]) => val === undefined).map(([key]) => key));
+        // Find missing properties that have validation errors (not in object at all)
+        const missingKeys = getMissingProperties(path, value, errors);
+        // Combine: defined entries + undefined entries with errors + missing properties
+        const undefinedKeysWithErrors = Array.from(undefinedEntryKeys).filter((key) => {
+            const propPath = NamingConvention_1.NamingConvention.variable(key)
+                ? `${path}.${key}`
+                : `${path}[${JSON.stringify(key)}]`;
+            return errors.some((e) => e.path.startsWith(propPath));
+        });
+        const allKeys = [
+            ...definedEntries.map(([key]) => key),
+            ...undefinedKeysWithErrors,
+            ...missingKeys,
+        ];
+        if (allKeys.length === 0) {
+            return `${indent}{}${errorComment}`;
+        }
+        const lines = [];
+        lines.push(`${indent}{${errorComment}`);
+        allKeys.forEach((key, index, array) => {
+            const propPath = NamingConvention_1.NamingConvention.variable(key)
+                ? `${path}.${key}`
+                : `${path}[${JSON.stringify(key)}]`;
+            const propIndent = "  ".repeat(tab + 1);
+            // Get the value (undefined for missing properties or undefined entries)
+            const val = missingKeys.includes(key) || undefinedKeysWithErrors.includes(key)
+                ? undefined
+                : // biome-ignore lint: intended
+                    value[key];
+            // Primitive property value (including undefined for missing properties)
+            if (val === undefined ||
+                val === null ||
+                typeof val === "boolean" ||
+                typeof val === "number" ||
+                typeof val === "string") {
+                const propErrorComment = getErrorComment(propPath, errors, usedErrors);
+                const keyStr = JSON.stringify(key);
+                const valueStr = val === undefined
+                    ? `${propIndent}${keyStr}: undefined`
+                    : `${propIndent}${keyStr}: ${JSON.stringify(val)}`;
+                const withComma = index < array.length - 1 ? `${valueStr},` : valueStr;
+                const line = withComma + propErrorComment;
+                lines.push(line);
+            }
+            // Complex property value (object or array)
+            else {
+                const keyLine = `${propIndent}${JSON.stringify(key)}: `;
+                let valStr = stringify({
+                    value: val,
+                    errors,
+                    path: propPath,
+                    tab: tab + 1,
+                    inArray: false,
+                    inToJson: false,
+                    usedErrors,
+                });
+                const valStrWithoutIndent = valStr.trimStart();
+                // Add comma before the error comment if not the last property
+                if (index < array.length - 1) {
+                    const valLines = valStrWithoutIndent.split("\n");
+                    const lastLine = valLines[valLines.length - 1];
+                    const commentIndex = lastLine.indexOf(" //");
+                    if (commentIndex !== -1) {
+                        valLines[valLines.length - 1] = `${lastLine.slice(0, commentIndex)},${lastLine.slice(commentIndex)}`;
+                    }
+                    else {
+                        valLines[valLines.length - 1] += ",";
+                    }
+                    valStr = valLines.join("\n");
+                }
+                else {
+                    valStr = valStrWithoutIndent;
+                }
+                const combined = keyLine + valStr;
+                lines.push(combined);
+            }
+        });
+        lines.push(`${indent}}`);
+        return lines.join("\n");
+    }
+    // Primitive types (null, boolean, number, string, undefined, etc.)
+    const valStr = value === undefined
+        ? "undefined"
+        : ((_a = JSON.stringify(value)) !== null && _a !== void 0 ? _a : String(value));
+    return `${indent}${valStr}${errorComment}`;
+}
+/** Get error comment for a given path */
+function getErrorComment(path, errors, usedErrors) {
+    const pathErrors = errors.filter((e) => e.path === path);
+    if (pathErrors.length === 0) {
+        return "";
+    }
+    // Mark these errors as used
+    pathErrors.forEach((e) => usedErrors.add(e));
+    return ` // ❌ ${JSON.stringify(pathErrors.map((e) => ({
+        path: e.path,
+        expected: e.expected,
+        description: e.description,
+    })))}`;
+}
+/**
+ * Check if there are missing array element errors (path ending with []) Returns
+ * an array of error objects, one per missing element
+ */
+function getMissingArrayElementErrors(path, errors, usedErrors) {
+    const wildcardPath = `${path}[]`;
+    const missingErrors = errors.filter((e) => e.path === wildcardPath);
+    // Mark these errors as used
+    missingErrors.forEach((e) => usedErrors.add(e));
+    return missingErrors;
+}
+/**
+ * Find missing properties that have validation errors but don't exist in the
+ * data Returns array of property keys that should be displayed as undefined
+ */
+function getMissingProperties(path, value, errors) {
+    const missingKeys = new Set();
+    for (const e of errors) {
+        // Check if error.path is a direct child of current path
+        const childKey = extractDirectChildKey(path, e.path);
+        if (childKey !== null) {
+            // Check if this property actually exists in the value
+            if (!(childKey in value)) {
+                missingKeys.add(childKey);
+            }
+        }
+    }
+    return Array.from(missingKeys);
+}
+/**
+ * Extract direct child property key if errorPath is a direct child of
+ * parentPath Returns null if not a direct child
+ *
+ * Examples:
+ *
+ * - ExtractDirectChildKey("$input", "$input.email") => "email"
+ * - ExtractDirectChildKey("$input", "$input.user.email") => null (grandchild)
+ * - ExtractDirectChildKey("$input.user", "$input.user.email") => "email"
+ * - ExtractDirectChildKey("$input", "$input[0]") => null (array index, not object
+ *   property)
+ * - ExtractDirectChildKey("$input", "$input["foo-bar"]") => "foo-bar"
+ * - ExtractDirectChildKey("$input", "$input["foo"]["bar"]") => null (grandchild)
+ */
+function extractDirectChildKey(parentPath, errorPath) {
+    if (!errorPath.startsWith(parentPath)) {
+        return null;
+    }
+    const suffix = errorPath.slice(parentPath.length);
+    // Match ".propertyName" pattern (direct child property with dot notation)
+    // Should not contain additional dots or brackets after the property name
+    const dotMatch = suffix.match(/^\.([^.[\]]+)$/);
+    if (dotMatch !== null) {
+        return dotMatch[1];
+    }
+    // Match '["key"]' pattern (direct child property with bracket notation)
+    // The key is a JSON-encoded string
+    const bracketMatch = suffix.match(/^\[("[^"\\]*(?:\\.[^"\\]*)*")\]$/);
+    if (bracketMatch !== null) {
+        try {
+            const parsed = JSON.parse(bracketMatch[1]);
+            // Ensure it's a string key, not a number (array index)
+            if (typeof parsed === "string") {
+                return parsed;
+            }
+        }
+        catch (_a) {
+            // Invalid JSON, ignore
+        }
+    }
+    return null;
+}
+//# sourceMappingURL=stringifyValidationFailure.js.map

package/lib/utils/stringifyValidationFailure.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stringifyValidationFailure.js","sourceRoot":"","sources":["../../src/utils/stringifyValidationFailure.ts"],"names":[],"mappings":"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"}

package/lib/utils/stringifyValidationFailure.mjs

@@ -0,0 +1,325 @@
+import { NamingConvention } from './NamingConvention.mjs';
+import { dedent } from './dedent.mjs';
+
+/**
+ * Format validation failure for LLM auto-correction feedback.
+ *
+ * When LLM generates invalid function call arguments, this produces annotated
+ * JSON with inline `// ❌` error comments at each invalid property. The output
+ * is wrapped in a markdown code block so that LLM can understand and correct
+ * its mistakes in the next turn.
+ *
+ * Below is an example of the output format:
+ *
+ * ```json
+ * {
+ *   "name": "John",
+ *   "age": "twenty", // ❌ [{"path":"$input.age","expected":"number & Type<\"uint32\">"}]
+ *   "email": "not-an-email", // ❌ [{"path":"$input.email","expected":"string & Format<\"email\">"}]
+ *   "hobbies": "reading" // ❌ [{"path":"$input.hobbies","expected":"Array<string>"}]
+ * }
+ * ```
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ * @param failure Validation failure from {@link ILlmFunction.validate}
+ * @returns Markdown code block with error-annotated JSON
+ */
+function stringifyValidationFailure(failure) {
+    const usedErrors = new Set();
+    const jsonOutput = stringify({
+        value: failure.data,
+        errors: failure.errors,
+        path: "$input",
+        tab: 0,
+        inArray: false,
+        inToJson: false,
+        usedErrors,
+    });
+    // Find errors that couldn't be embedded
+    const unmappableErrors = failure.errors.filter((e) => !usedErrors.has(e));
+    // If there are unmappable errors, append them as a separate block
+    if (unmappableErrors.length > 0)
+        return dedent `
+      \`\`\`json
+      ${jsonOutput}
+      \`\`\`
+
+      **Unmappable validation errors:**
+      \`\`\`json
+      ${JSON.stringify(unmappableErrors, null, 2)}
+      \`\`\`
+    `;
+    return dedent `
+    \`\`\`json
+    ${jsonOutput}
+    \`\`\`
+  `;
+}
+function stringify(props) {
+    const { value, errors, path, tab, inArray, inToJson, usedErrors } = props;
+    const indent = "  ".repeat(tab);
+    const errorComment = getErrorComment(path, errors, usedErrors);
+    // Handle undefined in arrays
+    if (inArray && value === undefined) {
+        return `${indent}undefined${errorComment}`;
+    }
+    // Array
+    if (Array.isArray(value)) {
+        // Check for missing array element errors (path[])
+        const missingElementErrors = getMissingArrayElementErrors(path, errors, usedErrors);
+        const hasMissingElements = missingElementErrors.length > 0;
+        if (value.length === 0) {
+            // Empty array but has missing element errors - show placeholders
+            if (hasMissingElements) {
+                const innerIndent = "  ".repeat(tab + 1);
+                const lines = [];
+                lines.push(`${indent}[${errorComment}`);
+                missingElementErrors.forEach((e, idx) => {
+                    const errComment = ` // ❌ ${JSON.stringify([{ path: e.path, expected: e.expected, description: e.description }])}`;
+                    const comma = idx < missingElementErrors.length - 1 ? "," : "";
+                    lines.push(`${innerIndent}undefined${comma}${errComment}`);
+                });
+                lines.push(`${indent}]`);
+                return lines.join("\n");
+            }
+            return `${indent}[]${errorComment}`;
+        }
+        const lines = [];
+        lines.push(`${indent}[${errorComment}`);
+        value.forEach((item, index) => {
+            const itemPath = `${path}[${index}]`;
+            const isLastElement = index === value.length - 1;
+            // If there are missing element errors, this is not truly the last line
+            const needsComma = !isLastElement || hasMissingElements;
+            let itemStr = stringify({
+                value: item,
+                errors,
+                path: itemPath,
+                tab: tab + 1,
+                inArray: true,
+                inToJson: false,
+                usedErrors,
+            });
+            // Add comma before the error comment if not the last element
+            if (needsComma) {
+                const itemLines = itemStr.split("\n");
+                const lastLine = itemLines[itemLines.length - 1];
+                const commentIndex = lastLine.indexOf(" //");
+                if (commentIndex !== -1) {
+                    itemLines[itemLines.length - 1] = `${lastLine.slice(0, commentIndex)},${lastLine.slice(commentIndex)}`;
+                }
+                else {
+                    itemLines[itemLines.length - 1] += ",";
+                }
+                itemStr = itemLines.join("\n");
+            }
+            lines.push(itemStr);
+        });
+        // Add missing element placeholders at the end for each [] error
+        if (hasMissingElements) {
+            const innerIndent = "  ".repeat(tab + 1);
+            missingElementErrors.forEach((e, idx) => {
+                const errComment = ` // ❌ ${JSON.stringify([{ path: e.path, expected: e.expected, description: e.description }])}`;
+                const comma = idx < missingElementErrors.length - 1 ? "," : "";
+                lines.push(`${innerIndent}undefined${comma}${errComment}`);
+            });
+        }
+        lines.push(`${indent}]`);
+        return lines.join("\n");
+    }
+    // Object
+    if (typeof value === "object" && value !== null) {
+        // Check for toJSON method
+        // biome-ignore lint: intended
+        if (!inToJson && typeof value.toJSON === "function") {
+            // biome-ignore lint: intended
+            const jsonValue = value.toJSON();
+            return stringify({
+                value: jsonValue,
+                errors,
+                path,
+                tab,
+                inArray,
+                inToJson: true,
+                usedErrors,
+            });
+        }
+        // Get all entries from the object (including undefined values that have errors)
+        const allEntries = Object.entries(value);
+        // Split into defined and undefined entries
+        const definedEntries = allEntries.filter(([_, val]) => val !== undefined);
+        const undefinedEntryKeys = new Set(allEntries.filter(([_, val]) => val === undefined).map(([key]) => key));
+        // Find missing properties that have validation errors (not in object at all)
+        const missingKeys = getMissingProperties(path, value, errors);
+        // Combine: defined entries + undefined entries with errors + missing properties
+        const undefinedKeysWithErrors = Array.from(undefinedEntryKeys).filter((key) => {
+            const propPath = NamingConvention.variable(key)
+                ? `${path}.${key}`
+                : `${path}[${JSON.stringify(key)}]`;
+            return errors.some((e) => e.path.startsWith(propPath));
+        });
+        const allKeys = [
+            ...definedEntries.map(([key]) => key),
+            ...undefinedKeysWithErrors,
+            ...missingKeys,
+        ];
+        if (allKeys.length === 0) {
+            return `${indent}{}${errorComment}`;
+        }
+        const lines = [];
+        lines.push(`${indent}{${errorComment}`);
+        allKeys.forEach((key, index, array) => {
+            const propPath = NamingConvention.variable(key)
+                ? `${path}.${key}`
+                : `${path}[${JSON.stringify(key)}]`;
+            const propIndent = "  ".repeat(tab + 1);
+            // Get the value (undefined for missing properties or undefined entries)
+            const val = missingKeys.includes(key) || undefinedKeysWithErrors.includes(key)
+                ? undefined
+                : // biome-ignore lint: intended
+                    value[key];
+            // Primitive property value (including undefined for missing properties)
+            if (val === undefined ||
+                val === null ||
+                typeof val === "boolean" ||
+                typeof val === "number" ||
+                typeof val === "string") {
+                const propErrorComment = getErrorComment(propPath, errors, usedErrors);
+                const keyStr = JSON.stringify(key);
+                const valueStr = val === undefined
+                    ? `${propIndent}${keyStr}: undefined`
+                    : `${propIndent}${keyStr}: ${JSON.stringify(val)}`;
+                const withComma = index < array.length - 1 ? `${valueStr},` : valueStr;
+                const line = withComma + propErrorComment;
+                lines.push(line);
+            }
+            // Complex property value (object or array)
+            else {
+                const keyLine = `${propIndent}${JSON.stringify(key)}: `;
+                let valStr = stringify({
+                    value: val,
+                    errors,
+                    path: propPath,
+                    tab: tab + 1,
+                    inArray: false,
+                    inToJson: false,
+                    usedErrors,
+                });
+                const valStrWithoutIndent = valStr.trimStart();
+                // Add comma before the error comment if not the last property
+                if (index < array.length - 1) {
+                    const valLines = valStrWithoutIndent.split("\n");
+                    const lastLine = valLines[valLines.length - 1];
+                    const commentIndex = lastLine.indexOf(" //");
+                    if (commentIndex !== -1) {
+                        valLines[valLines.length - 1] = `${lastLine.slice(0, commentIndex)},${lastLine.slice(commentIndex)}`;
+                    }
+                    else {
+                        valLines[valLines.length - 1] += ",";
+                    }
+                    valStr = valLines.join("\n");
+                }
+                else {
+                    valStr = valStrWithoutIndent;
+                }
+                const combined = keyLine + valStr;
+                lines.push(combined);
+            }
+        });
+        lines.push(`${indent}}`);
+        return lines.join("\n");
+    }
+    // Primitive types (null, boolean, number, string, undefined, etc.)
+    const valStr = value === undefined
+        ? "undefined"
+        : (JSON.stringify(value) ?? String(value));
+    return `${indent}${valStr}${errorComment}`;
+}
+/** Get error comment for a given path */
+function getErrorComment(path, errors, usedErrors) {
+    const pathErrors = errors.filter((e) => e.path === path);
+    if (pathErrors.length === 0) {
+        return "";
+    }
+    // Mark these errors as used
+    pathErrors.forEach((e) => usedErrors.add(e));
+    return ` // ❌ ${JSON.stringify(pathErrors.map((e) => ({
+        path: e.path,
+        expected: e.expected,
+        description: e.description,
+    })))}`;
+}
+/**
+ * Check if there are missing array element errors (path ending with []) Returns
+ * an array of error objects, one per missing element
+ */
+function getMissingArrayElementErrors(path, errors, usedErrors) {
+    const wildcardPath = `${path}[]`;
+    const missingErrors = errors.filter((e) => e.path === wildcardPath);
+    // Mark these errors as used
+    missingErrors.forEach((e) => usedErrors.add(e));
+    return missingErrors;
+}
+/**
+ * Find missing properties that have validation errors but don't exist in the
+ * data Returns array of property keys that should be displayed as undefined
+ */
+function getMissingProperties(path, value, errors) {
+    const missingKeys = new Set();
+    for (const e of errors) {
+        // Check if error.path is a direct child of current path
+        const childKey = extractDirectChildKey(path, e.path);
+        if (childKey !== null) {
+            // Check if this property actually exists in the value
+            if (!(childKey in value)) {
+                missingKeys.add(childKey);
+            }
+        }
+    }
+    return Array.from(missingKeys);
+}
+/**
+ * Extract direct child property key if errorPath is a direct child of
+ * parentPath Returns null if not a direct child
+ *
+ * Examples:
+ *
+ * - ExtractDirectChildKey("$input", "$input.email") => "email"
+ * - ExtractDirectChildKey("$input", "$input.user.email") => null (grandchild)
+ * - ExtractDirectChildKey("$input.user", "$input.user.email") => "email"
+ * - ExtractDirectChildKey("$input", "$input[0]") => null (array index, not object
+ *   property)
+ * - ExtractDirectChildKey("$input", "$input["foo-bar"]") => "foo-bar"
+ * - ExtractDirectChildKey("$input", "$input["foo"]["bar"]") => null (grandchild)
+ */
+function extractDirectChildKey(parentPath, errorPath) {
+    if (!errorPath.startsWith(parentPath)) {
+        return null;
+    }
+    const suffix = errorPath.slice(parentPath.length);
+    // Match ".propertyName" pattern (direct child property with dot notation)
+    // Should not contain additional dots or brackets after the property name
+    const dotMatch = suffix.match(/^\.([^.[\]]+)$/);
+    if (dotMatch !== null) {
+        return dotMatch[1];
+    }
+    // Match '["key"]' pattern (direct child property with bracket notation)
+    // The key is a JSON-encoded string
+    const bracketMatch = suffix.match(/^\[("[^"\\]*(?:\\.[^"\\]*)*")\]$/);
+    if (bracketMatch !== null) {
+        try {
+            const parsed = JSON.parse(bracketMatch[1]);
+            // Ensure it's a string key, not a number (array index)
+            if (typeof parsed === "string") {
+                return parsed;
+            }
+        }
+        catch {
+            // Invalid JSON, ignore
+        }
+    }
+    return null;
+}
+
+export { stringifyValidationFailure };
+//# sourceMappingURL=stringifyValidationFailure.mjs.map