Function annotateInternalPythonFields

scripts/codegen/utils.ts:767–800

(
    code: string,
    fieldsByType: Map<string, Set<string>>,
    toFieldName: (jsonName: string) => string
)

 * name (typically snake_case).
 */
export function annotateInternalPythonFields(
    code: string,
    fieldsByType: Map<string, Set<string>>,
    toFieldName: (jsonName: string) => string
): string {
    const escapeRegex = (s: string): string => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
    let result = code;
    for (const [typeName, fields] of fieldsByType) {
        // Match the class body up to the next top-level statement. quicktype's
        // generated classes are separated by blank-line boundaries.
        const classRe = new RegExp(
            `(@dataclass\\nclass ${escapeRegex(typeName)}[:(][^]*?)(?=\\n(?:@dataclass\\n)?class \\w|\\n\\nclass |\\n[A-Za-z_]\\w* =|$)`,
            "g"
        );
        result = result.replace(classRe, (block) => {
            for (const jsonField of fields) {
                const pyField = toFieldName(jsonField);
                const escaped = escapeRegex(pyField);
                // Match `    fieldName: type` style declarations (PEP 526). Avoid
                // double-annotating if the comment is already present immediately above.
                block = block.replace(
                    new RegExp(`(^(?!    # Internal:.*$)(?:.*\\n)?)(    )${escaped}(?=\\s*:)`, "gm"),
                    (_match, prefix, indent) => {
                        // Avoid duplicate annotation if the previous line is already an Internal: marker.
                        if (/    # Internal:/.test(prefix)) return `${prefix}${indent}${pyField}`;
                        return `${prefix}${indent}# Internal: this field is an internal SDK API and is not part of the public surface.\n${indent}${pyField}`;
                    }
                );
            }
            return block;
        });
    }
    return result;
}

/**
 * Walks a top-level JSON Schema and marks any property whose referenced type