genzig.zig

const std = @import("std");
const ArrayList = std.ArrayList;
const StringHashMap = std.StringHashMap;
const json = std.json;
const StringPool = @import("stringpool.zig").StringPool;
const path_sep = std.fs.path.sep_str;

const cameltosnake = @import("cameltosnake.zig");

const common = @import("common.zig");
const Nothing = common.Nothing;
const jsonPanic = common.jsonPanic;
const jsonPanicMsg = common.jsonPanicMsg;
const jsonEnforce = common.jsonEnforce;
const jsonEnforceMsg = common.jsonEnforceMsg;
const fmtJson = common.fmtJson;

var arena = std.heap.ArenaAllocator.init(std.heap.page_allocator);
const allocator = &arena.allocator;

const autogen_header = "//! NOTE: this file is autogenerated, DO NOT MODIFY\n";

var global_symbol_pool = StringPool.init(allocator);

var global_symbol_none : StringPool.Val = undefined;
var global_symbol_None : StringPool.Val = undefined;

var global_pass1: json.ObjectMap = undefined;
var global_notnull: json.ObjectMap = undefined;

const ValueType = enum {
    Byte,
    UInt16,
    Int32,
    UInt32,
    Int64,
    UInt64,
    Single,
    Double,
    String,
    PropertyKey,
};
const global_value_type_map = std.ComptimeStringMap(ValueType, .{
    .{ "Byte", ValueType.Byte },
    .{ "UInt16", ValueType.UInt16 },
    .{ "Int32", ValueType.Int32 },
    .{ "UInt32", ValueType.UInt32 },
    .{ "Int64", ValueType.Int64 },
    .{ "UInt64", ValueType.UInt64 },
    .{ "Single", ValueType.Single },
    .{ "Double", ValueType.Double },
    .{ "String", ValueType.String },
    .{ "PropertyKey", ValueType.PropertyKey },
});
fn valueTypeToZigType(t: ValueType) []const u8 {
    return switch (t) {
        .Byte   => return "u8",
        .UInt16 => return "u16",
        .Int32  => return "i32",
        .UInt32 => return "u32",
        .Int64  => return "i64",
        .UInt64 => return "u64",
        .Single => return "f32",
        .Double => return "f64",
        .String => return "[]const u8",
        .PropertyKey => @panic("cannot call valueTypeToZigType for ValueType.PropertyKey"),
    };
}

const Pass1TypeKindCategory = enum { default, ptr, com };
const pass1_type_kind_info = std.ComptimeStringMap(Pass1TypeKindCategory, .{
    .{ "Integral", .default },
    .{ "Enum", .default },
    .{ "Struct", .default },
    .{ "Union", .default },
    .{ "Com", .com },
    .{ "Pointer", .ptr },
    .{ "FunctionPointer", .ptr },
});

const NativeType = enum {
    Boolean,
    SByte,
    Byte,
    Int16,
    UInt16,
    Int32,
    UInt32,
    Int64,
    UInt64,
    Char,
    Single,
    Double,
    String,
    IntPtr,
    UIntPtr,
    Guid,
};
const global_native_type_map = std.ComptimeStringMap(NativeType, .{
    .{ "Boolean", NativeType.Boolean },
    .{ "SByte", NativeType.SByte },
    .{ "Byte", NativeType.Byte },
    .{ "Int16", NativeType.Int16 },
    .{ "UInt16", NativeType.UInt16 },
    .{ "Int32", NativeType.Int32 },
    .{ "UInt32", NativeType.UInt32 },
    .{ "Int64", NativeType.Int64 },
    .{ "UInt64", NativeType.UInt64 },
    .{ "Char", NativeType.Char },
    .{ "Single", NativeType.Single },
    .{ "Double", NativeType.Double },
    .{ "String", NativeType.String },
    .{ "IntPtr", NativeType.IntPtr },
    .{ "UIntPtr", NativeType.UIntPtr },
    .{ "Guid", NativeType.Guid },
});
fn nativeTypeToZigType(t: NativeType) []const u8 {
    return switch (t) {
        .Boolean => return "bool",
        .SByte => return "i8",
        .Byte => return "u8",
        .Int16 => return "i16",
        .UInt16 => return "u16",
        .Int32 => return "i32",
        .UInt32 => return "u32",
        .Int64 => return "i64",
        .UInt64 => return "u64",
        .Char => return "u16",
        .Single => return "f32",
        .Double => return "f64",
        .String => return "[]const u8",
        .IntPtr => return "isize",
        .UIntPtr => return "usize",
        .Guid => @panic("cannot call nativeTypeToZigType for NativeType.Guid"),
    };
}

const TargetKind = enum {
    Default,
    FunctionPointer,
    Com,
};
const target_kind_map = std.ComptimeStringMap(TargetKind, .{
    .{ "Default", TargetKind.Default },
    .{ "FunctionPointer", TargetKind.FunctionPointer },
    .{ "Com", TargetKind.Com },
});

const Module = struct {
    optional_parent: ?*Module,
    name: StringPool.Val,
    zig_basename: []const u8,
    children: StringPool.HashMap(*Module),
    file: ?SdkFile,
    pub fn alloc(optional_parent: ?*Module, name: StringPool.Val) !*Module {
        var module = try allocator.create(Module);
        module.* = Module {
            .optional_parent = optional_parent,
            .name = name,
            .zig_basename = try std.mem.concat(allocator, u8, &[_][]const u8 { name.slice, ".zig" }),
            .children = StringPool.HashMap(*Module).init(allocator),
            .file = null,
        };
        return module;
    }
};

const import_prefix_table = &[_][]const u8 {
    "",
    "../",
    "../../",
    "../../../",
    "../../../../",
};

const ApiImport = struct {
    arches: ArchFlags,
    api: StringPool.Val,
};

// TODO: this is defined in std, maybe it should be pub?
var failAllocator = std.mem.Allocator{
    .allocFn = failAllocatorAlloc,
    .resizeFn = std.mem.Allocator.noResize,
};
fn failAllocatorAlloc(self: *std.mem.Allocator, n: usize, alignment: u29, len_align: u29, ra: usize) std.mem.Allocator.Error![]u8 {
    _ = self;
    _ = n;
    _ = alignment;
    _ = len_align;
    _ = ra;
    return error.OutOfMemory;
}
const empty_json_object_map = json.ObjectMap {
    .ctx = .{ },
    .allocator = &failAllocator,
    .unmanaged = .{ },
};

const SdkFile = struct {
    json_basename: []const u8,
    json_name: []const u8,
    zig_name: []const u8,
    depth: u2,
    const_exports: ArrayList(StringPool.Val),
    uses_guid: bool,
    top_level_api_imports: StringPool.HashMap(ApiImport),
    type_exports: StringPool.HashMap(Nothing),
    func_exports: StringPool.HashMap(Nothing),
    // this field is only needed to workaround: https://github.com/ziglang/zig/issues/4476
    tmp_func_ptr_workaround_list: ArrayList(StringPool.Val),
    param_names_to_avoid_map_get_fn: *const fn(s: []const u8) ?Nothing,
    not_null_funcs: json.ObjectMap,
    not_null_funcs_applied: StringPool.HashMap(Nothing),

    pub fn getWin32DirImportPrefix(self: SdkFile) []const u8 {
        return import_prefix_table[self.depth];
    }
    pub fn getSrcDirImportPrefix(self: SdkFile) []const u8 {
        return import_prefix_table[self.depth + 1];
    }

    pub fn addApiImport(self: *SdkFile, arches: ArchFlags, name: []const u8, api: []const u8, parents: json.Array) !void {
        if (!std.mem.eql(u8, self.json_name, api)) {
            const top_level_symbol = try global_symbol_pool.add(
                if (parents.items.len == 0) name else parents.items[0].String);
            const pool_api = try global_symbol_pool.add(api);
            if (self.top_level_api_imports.getPtr(top_level_symbol)) |import| {
                jsonEnforceMsg(pool_api.eql(import.api), "symbol conflict '{s}', api mismatch '{s}' and '{s}'", .{name, pool_api, import.api});
                //jsonEnforceMsg(other.parents.len == 0, "symbol conflict '{s}', parents mismatch", .{name});
                const new_flags = import.arches.flags | arches.flags;
                if (new_flags != import.arches.flags) {
                    import.arches.flags = new_flags;
                }
            } else {
                try self.top_level_api_imports.put(top_level_symbol, .{ .arches = arches, .api = pool_api } );
            }
        }
    }
};

const notnull_filename: []const u8 = "notnull.json";

const Times = struct {
    parse_time_millis : i64 = 0,
    read_time_millis : i64 = 0,
    generate_time_millis : i64 = 0,
};
var global_times = Times {};

pub fn main() !u8 {
    return main2() catch |e| switch (e) {
        error.AlreadyReported => return 0xff,
        else => return e,
    };
}
fn main2() !u8 {
    const main_start_millis = std.time.milliTimestamp();
    var print_time_summary = false;
    defer {
        if (print_time_summary) {
            var total_millis = std.time.milliTimestamp() - main_start_millis;
            if (total_millis == 0) total_millis = 1; // prevent divide by 0
            std.debug.warn("Parse Time: {} millis ({}%)\n", .{global_times.parse_time_millis, @divTrunc(100 * global_times.parse_time_millis, total_millis)});
            std.debug.warn("Read Time : {} millis ({}%)\n", .{global_times.read_time_millis , @divTrunc(100 * global_times.read_time_millis, total_millis)});
            std.debug.warn("Gen Time  : {} millis ({}%)\n", .{global_times.generate_time_millis , @divTrunc(100 * global_times.generate_time_millis, total_millis)});
            std.debug.warn("Total Time: {} millis\n", .{total_millis});
        }
    }
    global_symbol_none = try global_symbol_pool.add("none");
    global_symbol_None = try global_symbol_pool.add("None");

    var win32json_dir = try common.openWin32JsonDir(std.fs.cwd());
    defer win32json_dir.close();

    const cwd = std.fs.cwd();

    const zigwin32_dir_name = "zigwin32";
    cwd.access(zigwin32_dir_name, .{}) catch |e| switch (e) {
        error.FileNotFound => {
            std.debug.warn("Error: repository '{s}' does not exist, clone it with:\n", .{zigwin32_dir_name});
            std.debug.warn("    git clone https://github.com/marlersoft/zigwin32 {s}" ++ path_sep ++ zigwin32_dir_name ++ "\n", .{
                try common.getcwd(allocator)
            });
            return error.AlreadyReported;
        },
        else => return e,
    };

    global_pass1 = try readJson("pass1.json");
    global_notnull = try readJson(notnull_filename);

    var out_dir = try cwd.openDir(zigwin32_dir_name, .{});
    defer out_dir.close();
    out_dir.deleteFile("win32.zig") catch |e| switch (e) {
        error.FileNotFound => {},
        else => return e,
    };
    try cleanDir(out_dir, "win32");
    var out_win32_dir = try out_dir.openDir("win32", .{});
    defer out_win32_dir.close();

    const src_modules = &[_][]const u8 {
        "zig",
        "missing",
        "windowlongptr",
    };

    const root_module = try Module.alloc(null, try global_symbol_pool.add("win32"));

    {
        var api_dir = try win32json_dir.openDir("api", .{.iterate = true}) ;
        defer api_dir.close();

        var api_list = std.ArrayList([]const u8).init(allocator);
        defer {
            for (api_list.items) |api_name| {
                allocator.free(api_name);
            }
            api_list.deinit();
        }
        try common.readApiList(api_dir, &api_list);

        // sort the list of APIs so our api order is not dependent on the file-system ordering
        std.sort.sort([]const u8, api_list.items, Nothing {}, common.asciiLessThanIgnoreCase);

        std.debug.warn("-----------------------------------------------------------------------\n", .{});
        std.debug.warn("loading {} api json files...\n", .{api_list.items.len});

        for (api_list.items) |api_json_basename, api_index| {
            const api_num = api_index + 1;
            std.debug.warn("{}/{}: loading '{s}'\n", .{api_num, api_list.items.len, api_json_basename});
            //
            // TODO: would things run faster if I just memory mapped the file?
            //
            var file = try api_dir.openFile(api_json_basename, .{});
            defer file.close();
            try readAndGenerateApiFile(root_module, out_win32_dir, api_json_basename, file);
        }

        for (src_modules ++ &[_][]const u8 {
            "everything",
        }) |submodule_str| {
            const submodule = try global_symbol_pool.add(submodule_str);
            try root_module.children.put(submodule, try Module.alloc(root_module, submodule));
        }

        try generateContainerModules(out_dir, root_module);
        try generateEverythingModule(out_win32_dir, root_module);
    }

    // copy zig.zig, missing.zig and windowlongptr.zig modules
    {
        var src_dir = try cwd.openDir("src", .{});
        defer src_dir.close();
        inline for (src_modules) |mod| {
            try src_dir.copyFile(mod ++ ".zig", out_win32_dir, mod ++ ".zig", .{});
        }
    }
    print_time_summary = true;
    return 0;
}


fn readJson(filename: []const u8) !std.json.ObjectMap {
    const content = blk: {
        const file = try std.fs.cwd().openFile(filename, .{});
        defer file.close();
        break :blk try file.readToEndAlloc(allocator, std.math.maxInt(usize));
    };

    var json_tree = blk: {
        var parser = json.Parser.init(allocator, false); // false is copy_strings
        defer parser.deinit();

        const start = if (std.mem.startsWith(u8, content, "\xEF\xBB\xBF")) 3 else @as(usize, 0);
        const json_content = content[start..];
        std.log.info("parsing '{s}'...", .{filename});
        break :blk try parser.parse(json_content);
    };
    return json_tree.root.Object;
}

fn gatherSdkFiles(sdk_files: *ArrayList(*SdkFile), module: *Module) anyerror!void {
    if (module.file) |_| {
        try sdk_files.append(&module.file.?);
    }
    const children = try allocMapValues(allocator, *Module, module.children);
    defer allocator.free(children);
    std.sort.sort(*Module, children, {}, moduleLessThan); // sort so the order is predictable
    for (children) |child| {
        try gatherSdkFiles(sdk_files, child);
    }
}

fn generateEverythingModule(out_win32_dir: std.fs.Dir, root_module: *Module) !void {
    var everything_file = try out_win32_dir.createFile("everything.zig", .{});
    defer everything_file.close();
    const writer = everything_file.writer();
    try writer.writeAll(removeCr(autogen_header ++
        \\//! This module contains aliases to ALL symbols inside the Win32 SDK.  It allows
        \\//! an application to access any and all symbols through a single import.
        \\
        \\pub const L = @import("zig.zig").L;
        \\
        \\pub usingnamespace @import("missing.zig");
        \\
    ));

    var sdk_files = ArrayList(*SdkFile).init(allocator);
    defer sdk_files.deinit();

    try gatherSdkFiles(&sdk_files, root_module);

    // TODO: workaround issue where constants/functions are defined more than once, not sure what the right solution
    //       is for all these, maybe some modules are not compatible with each other.  This could just be the permanent
    //       solution as well, if there are conflicts, we could just say the user has to import the specific module they want.
    // TODO: I think the right way to reslve conflicts in everything.zig is to have a priority order for the apis.
    //       If I just sort the API's in the right order, more common apis go first, then my current logic will work.
    var shared_export_map = StringPool.HashMap(*SdkFile).init(allocator);
    defer shared_export_map.deinit();

    // populate the shared_export_map, start with types first
    // because types can be referenced within the modules (unlike consts/functions)
    for (sdk_files.items) |sdk_file| {
        var type_export_it = sdk_file.type_exports.iterator();
        while (type_export_it.next()) |kv| {
            const type_name = kv.key_ptr.*;
            if (shared_export_map.get(type_name)) |_| {
                //try shared_export_map.put(type_name, .{ .first_sdk_file_ptr = entry.first_sdk_file_ptr, .duplicates = entry.duplicates + 1 });
            } else {
                //try shared_export_map.put(type_name, .{ .first_sdk_file_ptr = sdk_file, .duplicates = 0 });
                try shared_export_map.put(type_name, sdk_file);
            }
        }
    }

    for (sdk_files.items) |sdk_file| {
        try writer.print("// {s} exports {} constants:\n", .{sdk_file.zig_name, sdk_file.const_exports.items.len});
        for (sdk_file.const_exports.items) |constant| {
            if (shared_export_map.get(constant)) |other_sdk_file| {
                try writer.print("// WARNING: redifinition of constant symbol '{s}' in module '{s}' (going with module '{s}')\n", .{
                    constant, sdk_file.zig_name, other_sdk_file.zig_name});
            } else {
                try writer.print("pub const {s} = @import(\"../win32.zig\").{s}.{0s};\n", .{constant, sdk_file.zig_name});
                try shared_export_map.put(constant, sdk_file);
            }
        }
        try writer.print("// {s} exports {} types:\n", .{sdk_file.zig_name, sdk_file.type_exports.count()});
        var export_it = sdk_file.type_exports.iterator();
        while (export_it.next()) |kv| {
            const type_name = kv.key_ptr.*;
            const first_type_sdk = shared_export_map.get(type_name) orelse unreachable;
            if (first_type_sdk != sdk_file) {
                try writer.print("// WARNING: redefinition of type symbol '{s}' from '{s}', going with '{s}'\n", .{
                    type_name, sdk_file.zig_name, first_type_sdk.zig_name});
            } else {
                try writer.print("pub const {s} = @import(\"../win32.zig\").{s}.{0s};\n", .{type_name, sdk_file.zig_name});
            }
        }
        try writer.print("// {s} exports {} functions:\n", .{sdk_file.zig_name, sdk_file.func_exports.count()});
        var func_it = sdk_file.func_exports.iterator();
        while (func_it.next()) |kv| {
            const func = kv.key_ptr.*;
            if (shared_export_map.get(func)) |other_sdk_file| {
                try writer.print("// WARNING: redifinition of function '{s}' in module '{s}' (going with module '{s}')\n", .{
                    func, sdk_file.zig_name, other_sdk_file.zig_name});
            } else {
                try writer.print("pub const {s} = @import(\"../win32.zig\").{s}.{0s};\n", .{func, sdk_file.zig_name});
                try shared_export_map.put(func, sdk_file);
            }
        }
    }
}

fn allocMapValues(alloc: *std.mem.Allocator, comptime T: type, map: anytype) ![]T {
    var values = try alloc.alloc(T, map.count());
    errdefer alloc.free(values);
    {
        var i: usize = 0;
        var it = map.iterator(); while (it.next()) |entry| : (i += 1) {
            values[i] = entry.value_ptr.*;
        }
        std.debug.assert(i == map.count());
    }
    return values;
}

fn moduleLessThan(context: void, lhs: *Module, rhs: *Module) bool {
    _ = context;
    return std.ascii.lessThanIgnoreCase(lhs.name.slice, rhs.name.slice);
}

fn generateContainerModules(dir: std.fs.Dir, module: *Module) anyerror!void {
    if (module.children.count() == 0) {
        return;
    }

    var file = blk: {
        if (module.file) |_| {
            const file = try dir.openFile(module.zig_basename, .{ .read = false, .write = true });
            try file.seekFromEnd(0);
            break :blk file;
        }
        break :blk try dir.createFile(module.zig_basename, .{});
    };
    defer file.close();
    const writer = file.writer();


    const children = try allocMapValues(allocator, *Module, module.children);
    defer allocator.free(children);

    std.sort.sort(*Module, children, {}, moduleLessThan);
    if (module.file) |_| {
        try writer.print("//--------------------------------------------------------------------------------\n", .{});
        try writer.print("// Section: SubModules ({})\n", .{children.len});
        try writer.print("//--------------------------------------------------------------------------------\n", .{});
    } else {
        try writer.writeAll(autogen_header);
    }
    for (children) |child| {
        try writer.print("pub const {s} = @import(\"{s}/{0s}.zig\");\n", .{child.name, module.name.slice});
    }

    if (module.file) |_| { } else {
        try writer.writeAll(removeCr(
            \\test {
            \\    @import("std").testing.refAllDecls(@This());
            \\}
            \\
        ));
    }

    var next_dir = try dir.openDir(module.name.slice, .{});
    defer next_dir.close();

    for (children) |child| {
        try generateContainerModules(next_dir, child);
    }
}

fn readAndGenerateApiFile(root_module: *Module, out_dir: std.fs.Dir, json_basename: []const u8, file: std.fs.File) !void {

    const read_start_millis = std.time.milliTimestamp();
    const content = try file.readToEndAlloc(allocator, std.math.maxInt(usize));
    const read_end_millis = std.time.milliTimestamp();
    global_times.read_time_millis += read_end_millis - read_start_millis;
    defer allocator.free(content);
    std.debug.warn("  read {} bytes\n", .{content.len});

    // Parsing the JSON is VERY VERY SLOW!!!!!!
    var json_tree = blk: {
        var parser = json.Parser.init(allocator, false); // false is copy_strings
        defer parser.deinit();

        const start = if (std.mem.startsWith(u8, content, "\xEF\xBB\xBF")) 3 else @as(usize, 0);
        const json_content = content[start..];
        break :blk try parser.parse(json_content);
    };
    defer json_tree.deinit();
    global_times.parse_time_millis += std.time.milliTimestamp() - read_end_millis;


    const json_basename_copy = try std.mem.dupe(allocator, u8, json_basename);
    const json_name = json_basename_copy[0..json_basename_copy.len - ".json".len];
    const zig_name = try cameltosnake.camelToSnakeAlloc(allocator, json_name);
    errdefer allocator.free(zig_name);

    var module_dir = out_dir;
    defer if (module_dir.fd != out_dir.fd) module_dir.close();

    var module: *Module = root_module;
    var depth: u2 = 0;

    {
        var it = std.mem.tokenize(u8, zig_name, ".");
        while (it.next()) |name_part| {
            if (module != root_module) {
                depth += 1;
                if (module.children.count() == 0) {
                    try module_dir.makeDir(module.name.slice);
                }
                const next_dir = try module_dir.openDir(module.name.slice, .{});
                if (module_dir.fd != out_dir.fd)
                    module_dir.close();
                module_dir = next_dir;
            }

            const name_pool = try global_symbol_pool.add(name_part);
            if (module.children.get(name_pool)) |existing| {
                module = existing;
            } else {
                const new_module = try Module.alloc(module, name_pool);
                try module.children.put(name_pool, new_module);
                module = new_module;
            }
        }
    }

    if (module.file) |_| {
        jsonPanicMsg("qualified name '{s}' already has an sdk file?", .{zig_name});
    }

    var not_null_funcs = empty_json_object_map;
    if (global_notnull.get(json_name)) |*api_node| {
        const api_obj = api_node.Object;
        try jsonObjEnforceKnownFieldsOnly(api_obj, &[_][]const u8 {"Functions"}, notnull_filename);
        not_null_funcs = (try jsonObjGetRequired(api_obj, "Functions", notnull_filename)).Object;
    }

    module.file = SdkFile {
        .json_basename = json_basename_copy,
        .json_name = json_name,
        .zig_name = zig_name,
        .depth = depth,
        .const_exports = ArrayList(StringPool.Val).init(allocator),
        .uses_guid = false,
        .top_level_api_imports = StringPool.HashMap(ApiImport).init(allocator),
        .type_exports = StringPool.HashMap(Nothing).init(allocator),
        .func_exports = StringPool.HashMap(Nothing).init(allocator),
        .tmp_func_ptr_workaround_list = ArrayList(StringPool.Val).init(allocator),
        .param_names_to_avoid_map_get_fn = getParamNamesToAvoidMapGetFn(json_name),
        .not_null_funcs = not_null_funcs,
        .not_null_funcs_applied = StringPool.HashMap(Nothing).init(allocator),
    };

    const generate_start_millis = std.time.milliTimestamp();
    try generateFile(module_dir, module, json_tree);
    global_times.generate_time_millis += std.time.milliTimestamp() - generate_start_millis;
}

pub fn EmptyComptimeStringMap(comptime V: type) type { return struct {
    pub fn get(str: []const u8) ?V { _ = str; return null; }
};}

fn generateFile(module_dir: std.fs.Dir, module: *Module, tree: json.ValueTree) !void {
    const sdk_file = &module.file.?;

    var out_file = try module_dir.createFile(module.zig_basename, .{});
    defer out_file.close();
    var code_writer = CodeWriter { .writer = out_file.writer(), .depth = 0, .midline = false };
    const writer = &code_writer;

    try writer.writeBlock(autogen_header);
    // We can't import the everything module because it will re-introduce the same symbols we are exporting
    //try writer.print("usingnamespace @import(\"everything.zig\");\n", .{});
    const root_obj = tree.root.Object;
    const constants_array = (try jsonObjGetRequired(root_obj, "Constants", sdk_file)).Array;
    const types_array = (try jsonObjGetRequired(root_obj, "Types", sdk_file)).Array;
    const functions_array = (try jsonObjGetRequired(root_obj, "Functions", sdk_file)).Array;
    const unicode_aliases = (try jsonObjGetRequired(root_obj, "UnicodeAliases", sdk_file)).Array;
    try writer.line("//--------------------------------------------------------------------------------");
    try writer.linef("// Section: Constants ({})", .{constants_array.items.len});
    try writer.line("//--------------------------------------------------------------------------------");
    for (constants_array.items) |*constant_node_ptr| {
        try generateConstant(sdk_file, writer, constant_node_ptr.Object);
    }
    std.debug.assert(constants_array.items.len == sdk_file.const_exports.items.len);
    try writer.line("");
    try writer.line("//--------------------------------------------------------------------------------");
    try writer.linef("// Section: Types ({})", .{types_array.items.len});
    try writer.line("//--------------------------------------------------------------------------------");
    {
        var enum_alias_conflicts = StringPool.HashMap(StringPool.Val).init(allocator);
        defer enum_alias_conflicts.deinit();
        for (types_array.items) |*type_node_ptr| {
            try generateType(sdk_file, writer, type_node_ptr.Object, &enum_alias_conflicts);
            try writer.line("");
        }
    }
    try writer.line("");
    try writer.line("//--------------------------------------------------------------------------------");
    try writer.linef("// Section: Functions ({})", .{functions_array.items.len});
    try writer.line("//--------------------------------------------------------------------------------");
    for (functions_array.items) |*function_node_ptr| {
        try generateFunction(sdk_file, writer, function_node_ptr.Object, .fixed, null, null);
        try writer.line("");
    }
    std.debug.assert(functions_array.items.len >= sdk_file.func_exports.count());
    try writer.line("");
    try writer.line("//--------------------------------------------------------------------------------");
    try writer.linef("// Section: Unicode Aliases ({})", .{unicode_aliases.items.len});
    try writer.line("//--------------------------------------------------------------------------------");
    try generateUnicodeAliases(sdk_file, writer, unicode_aliases.items);
    const import_total = @boolToInt(sdk_file.uses_guid) + sdk_file.top_level_api_imports.count();
    try writer.line("//--------------------------------------------------------------------------------");
    try writer.linef("// Section: Imports ({})", .{import_total});
    try writer.line("//--------------------------------------------------------------------------------");
    if (sdk_file.uses_guid) {
        try writer.linef("const Guid = @import(\"{s}zig.zig\").Guid;", .{sdk_file.getWin32DirImportPrefix()});
    }
    {
        // TODO: the generated code would probalby be cleaner if I combine symbols
        //       that belong to the same arch set
        var it = sdk_file.top_level_api_imports.iterator();
        while (it.next()) |import| {
            const name = import.key_ptr.*;
            const api_upper = import.value_ptr.api;
            const arches = import.value_ptr.arches;

            // TODO: should I cache this mapping from api ref to api import path?
            const api_path = try cameltosnake.camelToSnakeAlloc(allocator, api_upper.slice);
            defer allocator.free(api_path);
            for (api_path) |c, i| {
                if (c == '.')
                    api_path[i] = '/';
            }
            var vis: []const u8 = "";
            if (arches.flags != ArchFlags.all.flags) {
                try generateArchPrefix(writer, sdk_file.depth, arches, "");
                writer.depth += 1;
                vis = "pub ";
            }
            try writer.linef("{s}const {s} = @import(\"{s}{s}.zig\").{1s};",
                .{vis, name, sdk_file.getWin32DirImportPrefix(), api_path});
            if (arches.flags != ArchFlags.all.flags) {
                writer.depth -= 1;
                generateArchSuffix(writer);
            }
        }
    }

    try writer.writeBlock(comptime removeCr(
        \\
        \\test {
        \\
    ));
    if (sdk_file.tmp_func_ptr_workaround_list.items.len > 0) {
        try writer.line("    // The following '_ = <FuncPtrType>' lines are a workaround for https://github.com/ziglang/zig/issues/4476");
        for (sdk_file.tmp_func_ptr_workaround_list.items) |func_ptr_type| {
            try writer.linef("    if (@hasDecl(@This(), \"{s}\")) {{ _ = {0s}; }}", .{func_ptr_type});
        }
        try writer.line("");
    }
    try writer.writeBlock(comptime removeCr(
        \\    @setEvalBranchQuota(
        \\        @import("std").meta.declarations(@This()).len * 3
        \\    );
        \\
        \\    // reference all the pub declarations
        \\    if (!@import("std").builtin.is_test) return;
        \\    inline for (@import("std").meta.declarations(@This())) |decl| {
        \\        if (decl.is_pub) {
        \\            _ = decl;
        \\        }
        \\    }
        \\}
        \\
    ));

    // check that all notnull stuff was applied
    {
        var it = sdk_file.not_null_funcs.iterator();
        var error_count : u32 = 0;
        while (it.next()) |api| {
            const pool_name = try global_symbol_pool.add(api.key_ptr.*);
            if (sdk_file.not_null_funcs_applied.get(pool_name)) |_| { } else {
                std.log.err("notnull.json api '{s}' function '{s}' was not applied", .{sdk_file.json_name, pool_name});
                error_count += 1;
            }
        }
        sdk_file.not_null_funcs_applied.deinit();
        if (error_count > 0) {
            return error.AlreadyReported;
        }
    }
}

fn typeIsVoid(type_obj: json.ObjectMap, sdk_file: *SdkFile) !bool {
    const kind = (try jsonObjGetRequired(type_obj, "Kind", sdk_file)).String;
    if (std.mem.eql(u8, kind, "Native")) {
        const name = (try jsonObjGetRequired(type_obj, "Name", sdk_file)).String;
        return std.mem.eql(u8, name, "void");
    }
    return false;
}

// convenient function that combines both adding type refs and creating a formatter
// for the type.   These 2 operations are orthogonal, however, combining them helps ensure
// that generating a type reference is not done without also adding that reference to the api
// being generated.
fn addTypeRefs(sdk_file: *SdkFile, arches: ArchFlags, type_ref: json.ObjectMap, options: TypeRefFormatter.Options, nested_context: ?*const NestedContext) anyerror!TypeRefFormatter {
    try addTypeRefsNoFormatter(sdk_file, arches, type_ref);
    return fmtTypeRef(type_ref, arches, options, nested_context);
}

fn addTypeRefsNoFormatter(sdk_file: *SdkFile, arches: ArchFlags, type_ref: json.ObjectMap) anyerror!void {
    const kind = (try jsonObjGetRequired(type_ref, "Kind", sdk_file)).String;
    if (std.mem.eql(u8, kind, "Native")) {
        try jsonObjEnforceKnownFieldsOnly(type_ref, &[_][]const u8 {"Kind", "Name"}, sdk_file);
        const name = (try jsonObjGetRequired(type_ref, "Name", sdk_file)).String;
        if (std.mem.eql(u8, name, "Void")) {
            // void is special
        } else if (std.mem.eql(u8, name, "Guid")) {
            sdk_file.uses_guid = true;
        } else if (global_native_type_map.get(name) == null) {
            std.debug.panic("unknown Native type '{s}'", .{name});
        }
    } else if (std.mem.eql(u8, kind, "ApiRef")) {
        try jsonObjEnforceKnownFieldsOnly(type_ref, &[_][]const u8 {"Kind", "Name", "TargetKind", "Api", "Parents"}, sdk_file);
        const tmp_name = (try jsonObjGetRequired(type_ref, "Name", sdk_file)).String;
        const api = (try jsonObjGetRequired(type_ref, "Api", sdk_file)).String;
        const parents = (try jsonObjGetRequired(type_ref, "Parents", sdk_file)).Array;
        try sdk_file.addApiImport(arches, tmp_name, api, parents);
    } else if (std.mem.eql(u8, kind, "PointerTo")) {
        try jsonObjEnforceKnownFieldsOnly(type_ref, &[_][]const u8 {"Kind", "Child"}, sdk_file);
        try addTypeRefsNoFormatter(sdk_file, arches, (try jsonObjGetRequired(type_ref, "Child", sdk_file)).Object);
    } else if (std.mem.eql(u8, kind, "Array")) {
        try jsonObjEnforceKnownFieldsOnly(type_ref, &[_][]const u8 {"Kind", "Shape", "Child"}, sdk_file);
        try addTypeRefsNoFormatter(sdk_file, arches, (try jsonObjGetRequired(type_ref, "Child", sdk_file)).Object);
    } else if (std.mem.eql(u8, kind, "LPArray")) {
        try jsonObjEnforceKnownFieldsOnly(type_ref, &[_][]const u8 {"Kind", "NullNullTerm", "CountConst", "CountParamIndex", "Child"}, sdk_file);
        try addTypeRefsNoFormatter(sdk_file, arches, (try jsonObjGetRequired(type_ref, "Child", sdk_file)).Object);
    } else if (std.mem.eql(u8, kind, "MissingClrType")) {
        try jsonObjEnforceKnownFieldsOnly(type_ref, &[_][]const u8 {"Kind", "Name", "Namespace"}, sdk_file);
    } else {
        jsonPanicMsg("kind '{s}' is not implemented", .{kind});
    }
}

const ContainerKind = enum { Struct, Union };
pub fn getAnonKind(s: []const u8) ?ContainerKind {
    //if (std.mem.startsWith(u8, s, "_Anonymous")) {
        if (std.mem.endsWith(u8, s, "_e__Struct"))
            return .Struct;
        if (std.mem.endsWith(u8, s, "_e__Union"))
            return .Union;
    //    jsonPanicMsg("type '{s}' starts with '_Anonymous' but does not have an expected end", .{s});
    //}
    return null;
}

// Provides access to nested types accessible from the current scope
const NestedContext = struct {
    nested_types: json.Array,
    parent: ?*const NestedContext,

    pub fn contains(self: NestedContext, name: []const u8) bool {
        std.debug.assert(self.nested_types.items.len > 0);
        for (self.nested_types.items) |*nested_type_node_ptr| {
            const nested_type_obj = nested_type_node_ptr.Object;
            const nested_name = (nested_type_obj.get("Name") orelse jsonPanic()).String;
            if (std.mem.eql(u8, nested_name, name))
                return true;
        }
        if (self.parent) |p| return p.contains(name);
        return false;
    }
};

const NullModifier = u3;

// we need to know if the type is the top-level type or a child type of something like a pointer
// so we can generate the correct `void` type.  Top level void types become void, but pointers
// to void types must become pointers to the `c_void` type.
// Need to know if it is an array specifically because array pointers cannot point to opaque types
// with an unknown size.
const DepthContext = enum {top_level, child, array};
const TypeRefFormatter = struct {
    pub const Reason = enum { var_decl, direct_type_access };
    pub const Options = struct {
        reason: Reason,
        is_const: bool = false,
        in: bool = false,
        out: bool = false,
        optional: bool = false,
        // TODO: handle this option
        not_null_term: bool = false,
        // TODO: handle this option
        null_null_term: bool = true,
        // TODO: what to do with this?
        ret_val: bool = false,
        // TODO: don't know what to do with this yet
        com_out_ptr: bool = false,
        // TODO: don't know what to do with this yet
        do_not_release: bool = false,
        // TODO: don't know what to do with this yet
        reserved: bool = false,
        optional_bytes_param_index: ?i16 = null,
        anon_types: ?*const AnonTypes,

        null_modifier: NullModifier,
    };

    type_ref: json.ObjectMap,
    arches: ArchFlags,
    options: Options,
    nested_context: ?*const NestedContext,
};
pub fn fmtTypeRef(type_ref: json.ObjectMap, arches: ArchFlags, options: TypeRefFormatter.Options, nested_context: ?*const NestedContext) TypeRefFormatter {
    return .{ .type_ref = type_ref, .arches = arches, .options = options, .nested_context = nested_context };
}

fn generateTypeRef(sdk_file: *SdkFile, writer: *CodeWriter, self: TypeRefFormatter) !void {
    try generateTypeRefRec(sdk_file, writer, self, .top_level);
}
fn generateTypeRefRec(sdk_file: *SdkFile, writer: *CodeWriter, self: TypeRefFormatter, depth_context: DepthContext) anyerror!void {
    const kind = (try jsonObjGetRequired(self.type_ref, "Kind", sdk_file)).String;
    if (std.mem.eql(u8, kind, "Native")) {
        try jsonObjEnforceKnownFieldsOnly(self.type_ref, &[_][]const u8 {"Kind", "Name"}, sdk_file);
        const name = (try jsonObjGetRequired(self.type_ref, "Name", sdk_file)).String;
        if (std.mem.eql(u8, name, "Void")) {
            const type_name: []const u8 = switch (depth_context) {
                .top_level => "void",
                .child => "c_void",
                // if we are rendering the element of an array, then we have to know the size, we default to u8
                // because most void pointers in C are measured in terms of u8 bytes
                .array => "u8",
            };
            try writer.writef("{s}", .{type_name}, .{.start=.any,.nl=false});
        } else if (std.mem.eql(u8, name, "Guid")) {
            try writer.write("Guid", .{.start=.any,.nl=false});
        } else {
            const native_type = global_native_type_map.get(name) orelse std.debug.panic("unknown Native type '{s}'", .{name});
            try writer.writef("{s}", .{nativeTypeToZigType(native_type)}, .{.start=.any,.nl=false});
        }
    } else if (std.mem.eql(u8, kind, "ApiRef")) {
        try jsonObjEnforceKnownFieldsOnly(self.type_ref, &[_][]const u8 {"Kind", "Name", "TargetKind", "Api", "Parents"}, sdk_file);
        const name = (try jsonObjGetRequired(self.type_ref, "Name", sdk_file)).String;
        const api = (try jsonObjGetRequired(self.type_ref, "Api", sdk_file)).String;

        if (getAnonKind(name)) |anon_kind| {
            const anon_types = self.options.anon_types orelse
                jsonPanicMsg("missing anonymous type '{s}' (this scope does not have any anonymous types)!", .{name});
            const name_pool = try global_symbol_pool.add(name);
            const type_obj = anon_types.types.get(name_pool) orelse
                jsonPanicMsg("missing anonymous type '{s}'!", .{name});
            try generateStructOrUnionDef(sdk_file, writer, type_obj, self.arches, anon_kind, self.nested_context);
            try writer.write("}", .{.nl=false});
            return;
        }

        const parents = (try jsonObjGetRequired(self.type_ref, "Parents", sdk_file)).Array;

        const type_kind_category = blk: {
            const pass1_api_map = (global_pass1.get(api) orelse
                jsonPanicMsg("type '{s}' is from API '{s}' that is missing from pass1 data", .{name, api})).Object;
            const pass1_type_obj = (pass1_api_map.get(name) orelse {
                if (parents.items.len == 0) {
                    const in_nested_context = if (self.nested_context) |c| c.contains(name) else false;
                    if (!in_nested_context) {
                        jsonPanicMsg("type '{s}' from API '{s}' is missing from pass1 data, has no parents and is not in the current nested context!", .{name, api});
                    }
                }
                // this means its a nested type which are always structs/unions
                break :blk Pass1TypeKindCategory.default;
            }).Object;
            try jsonObjEnforceKnownFieldsOnly(pass1_type_obj, &[_][]const u8 {"Kind"}, sdk_file);
            const type_kind = (try jsonObjGetRequired(pass1_type_obj, "Kind", sdk_file)).String;
            break :blk pass1_type_kind_info.get(type_kind) orelse
                jsonPanicMsg("unknown pass1 type kind '{s}'", .{type_kind});
        };

        if (self.options.reason == .var_decl) {
            switch (type_kind_category) {
                .default => {},
                .ptr => {
                    if (self.options.null_modifier & 1 == 0) {
                        try writer.write("?", .{.start=.any,.nl=false});
                    }
                },
                .com => {
                    if (self.options.null_modifier & 1 == 0) {
                        try writer.write("?", .{.start=.any,.nl=false});
                    }
                    try writer.write("*", .{.start=.any,.nl=false});
                },
            }
        }

        // special handling for PSTR and PWSTR for now.  This is because those types
        // have hardcoded non-const and null-terminated, so we can't reference them if our usage
        // doesn't match.
        // If there are more cases that behave like this, I will likely need to implement a 2-pass
        // system where the first pass I gather all the type definitions so that on the second pass
        // I'll know whether each type is a pointer like this and can fix things like this.
        const special : enum { pstr, pwstr, other } = blk: {
            if (std.mem.eql(u8, name, "PSTR")) break :blk .pstr;
            if (std.mem.eql(u8, name, "PWSTR")) break :blk .pwstr;
            break :blk .other;
        };
        if (special == .pstr or special == .pwstr) {
            // if we deviated from the options we set for PSTR/PWSTR, then generate the native zig
            // type directly instead of referencing the PSTR/PWSTR type
            if (self.options.is_const or self.options.not_null_term) {
                // can't put these expressions in the print argument tuple because of https://github.com/ziglang/zig/issues/8036
                const base_type = if (special == .pstr) "u8" else "u16";
                const sentinel_suffix = if (self.options.not_null_term) "" else ":0";
                const const_str = if (self.options.is_const) "const " else "";
                try writer.writef("[*{s}]{s}{s}", .{sentinel_suffix, const_str, base_type}, .{.start=.any,.nl=false});
                return;
            }
        }

        // for now, all nested type references MUST be in the same scope so this
        // just causes issues
        //for (parents.items) |*parent_ptr| {
        //    try writer.writef("{s}", .{parent_ptr.String}, .{.start=.any,.nl=false});
        //    try writer.write(".", .{.start=.any,.nl=false});
        //}
        try writer.writef("{s}", .{name}, .{.start=.any,.nl=false});
    } else if (std.mem.eql(u8, kind, "PointerTo")) {
        try jsonObjEnforceKnownFieldsOnly(self.type_ref, &[_][]const u8 {"Kind", "Child"}, sdk_file);
        const child = (try jsonObjGetRequired(self.type_ref, "Child", sdk_file)).Object;
        var child_options = self.options;
        if (self.options.reason == .var_decl and self.options.null_modifier & 1 == 0) {
            try writer.write("?", .{.start=.any,.nl=false});
        }
        child_options.null_modifier = self.options.null_modifier >> 1;
        try writer.write("*", .{.start=.any,.nl=false});
        if (self.options.is_const) {
            child_options.is_const = false; // TODO: is this right?
            try writer.write("const ", .{.start=.any,.nl=false});
        }
        try generateTypeRefRec(sdk_file, writer, fmtTypeRef(child, self.arches, child_options, self.nested_context), .child);
    } else if (std.mem.eql(u8, kind, "Array")) {
        try jsonObjEnforceKnownFieldsOnly(self.type_ref, &[_][]const u8 {"Kind", "Shape", "Child"}, sdk_file);
        const child = (try jsonObjGetRequired(self.type_ref, "Child", sdk_file)).Object;
        const shape_size = init: { switch (try jsonObjGetRequired(self.type_ref, "Shape", sdk_file)) {
            // TODO: should we use size 1 here?
            .Null => break :init 1,
            .Object => |shape_obj| {
                try jsonObjEnforceKnownFieldsOnly(shape_obj, &[_][]const u8 {"Size"}, sdk_file);
                break :init (try jsonObjGetRequired(shape_obj, "Size", sdk_file)).Integer;
            },
            else => jsonPanic(),
        }};
        try writer.writef("[{}]", .{shape_size}, .{.start=.any,.nl=false});
        try generateTypeRefRec(sdk_file, writer, fmtTypeRef(child, self.arches, self.options, self.nested_context), .child);
    } else if (std.mem.eql(u8, kind, "LPArray")) {
        try jsonObjEnforceKnownFieldsOnly(self.type_ref, &[_][]const u8 {"Kind", "NullNullTerm", "CountConst", "CountParamIndex", "Child"}, sdk_file);
        const null_null_term = (try jsonObjGetRequired(self.type_ref, "NullNullTerm", sdk_file)).Bool;
        const count_const = (try jsonObjGetRequired(self.type_ref, "CountConst", sdk_file)).Integer;
        const count_param_index = (try jsonObjGetRequired(self.type_ref, "CountParamIndex", sdk_file)).Integer;
        _ = count_param_index; // ignored for now
        const type_ref_kind = (try jsonObjGetRequired(self.type_ref, "Kind", sdk_file)).String;
        _ = type_ref_kind; // ignored for now
        // TODO: can Zig use count_param_index?
        const child = (try jsonObjGetRequired(self.type_ref, "Child", sdk_file)).Object;
        var child_options = self.options;
        if (self.options.optional) {
            child_options.optional = false;
            try writer.write("?", .{.start=.any,.nl=false});
        }
        if (null_null_term) {
            try writer.write("*extern struct{{comment:[*]const u8=\"TODO: LPArray with null_null_term\"}}", .{.start=.any,.nl=false});
        } else {
            var sentinel_suffix: []const u8 = "";
            if ((!self.options.not_null_term) and isByteOrCharOrUInt16Type(child, sdk_file)) {
                sentinel_suffix = ":0";
            }

            if (count_const == -1 or count_const == 0) {
                try writer.writef("[*{s}]", .{sentinel_suffix}, .{.start=.any,.nl=false});
            } else {
                try writer.writef("*[{}]", .{count_const}, .{.start=.any,.nl=false});
            }
            if (count_const <= 0 and self.options.is_const)
                try writer.write("const ", .{.start=.any,.nl=false});
            try generateTypeRefRec(sdk_file, writer, fmtTypeRef(child, self.arches, child_options, self.nested_context), .array);
        }
    } else if (std.mem.eql(u8, kind, "MissingClrType")) {
        try jsonObjEnforceKnownFieldsOnly(self.type_ref, &[_][]const u8 {"Kind", "Name", "Namespace"}, sdk_file);
        const name = (try jsonObjGetRequired(self.type_ref, "Name", sdk_file)).String;
        const namespace = (try jsonObjGetRequired(self.type_ref, "Namespace", sdk_file)).String;
        try writer.writef("*struct{{comment: []const u8 = \"MissingClrType {s}.{s}\"}}", .{name, namespace}, .{.start=.any,.nl=false});
    } else {
        jsonPanicMsg("fmtTypeRef kind '{s}' is not implemented", .{kind});
    }
}

fn isByteOrCharOrUInt16Type(type_obj: json.ObjectMap, sdk_file: *SdkFile) bool {
    const kind = (try jsonObjGetRequired(type_obj, "Kind", sdk_file)).String;
    if (!std.mem.eql(u8, kind, "Native"))
        return false;

    const name = (try jsonObjGetRequired(type_obj, "Name", sdk_file)).String;
    if (std.mem.eql(u8, name, "Void"))
        return false;
    const native_type = global_native_type_map.get(name) orelse jsonPanicMsg("unknown Native type '{s}'", .{name});
    return switch (native_type) {
        .Byte, .Char, .UInt16 => true,
        else => false,
    };
}

fn fmtConstValue(value_type: ValueType, value: json.Value, sdk_file: *SdkFile) ConstValueFormatter {
    return .{ .value_type = value_type, .value = value, .sdk_file = sdk_file };
}
const ConstValueFormatter = struct {
    value_type: ValueType,
    value: json.Value,
    sdk_file: *SdkFile,
    pub fn format(
        self: @This(),
        comptime fmt: []const u8,
        options: std.fmt.FormatOptions,
        writer: anytype,
    ) std.os.WriteError!void {
        _ = fmt;
        _ = options;
        if (self.value_type == .String) {
            try writer.print("{}", .{fmtJson(self.value)});
            return;
        }
        const zig_type = valueTypeToZigType(self.value_type);
        if (self.value_type == .Single or self.value_type == .Double) {
            switch (self.value) {
                .String => |float_str| {
                    if (std.mem.eql(u8, float_str, "inf")) {
                        try writer.print("@import(\"std\").math.inf({s})", .{zig_type});
                        return;
                    } else if (std.mem.eql(u8, float_str, "-inf")) {
                        try writer.print("-@import(\"std\").math.inf({s})", .{zig_type});
                        return;
                    } else if (std.mem.eql(u8, float_str, "nan")) {
                        try writer.print("@import(\"std\").math.nan({s})", .{zig_type});
                        return;
                    } else {
                        std.debug.panic("unexpected float string value '{s}'", .{float_str});
                    }
                    return;
                },
                else => {},
            }
        }
        try writer.print("@as({s}, {})", .{zig_type, fmtJson(self.value)});
    }
};

const constants_to_skip = std.ComptimeStringMap(Nothing, .{
    // skip this constant because its name conflicts with the name of a type!
    .{ "PEERDIST_RETRIEVAL_OPTIONS_CONTENTINFO_VERSION", .{} },
    // skip these because these constants are integer values being cast to string pointers, however,
    // those string pointers need to be aligned.  The types that accept these constants should probably
    // be properly declared as union types.
    .{ "RT_CURSOR", .{} },
    .{ "RT_BITMAP", .{} },
    .{ "RT_ICON", .{} },
    .{ "RT_MENU", .{} },
    .{ "RT_DIALOG", .{} },
    .{ "RT_FONTDIR", .{} },
    .{ "RT_FONT", .{} },
    .{ "RT_ACCELERATOR", .{} },
    .{ "RT_MESSAGETABLE", .{} },
    .{ "RT_VERSION", .{} },
    .{ "RT_DLGINCLUDE", .{} },
    .{ "RT_PLUGPLAY", .{} },
    .{ "RT_VXD", .{} },
    .{ "RT_ANICURSOR", .{} },
    .{ "RT_ANIICON", .{} },
    .{ "RT_HTML", .{} },

    //.{ "IDC_ARROW", .{} }, This one is aligned so we can generate it
    .{ "IDC_IBEAM", .{} },
    .{ "IDC_WAIT", .{} },
    .{ "IDC_CROSS", .{} },
    .{ "IDC_UPARROW", .{} },
    .{ "IDC_SIZE", .{} },
    .{ "IDC_ICON", .{} },
    .{ "IDC_SIZENWSE", .{} },
    .{ "IDC_SIZENESW", .{} },
    .{ "IDC_SIZEWE", .{} },
    .{ "IDC_SIZENS", .{} },
    .{ "IDC_SIZEALL", .{} },
    .{ "IDC_NO", .{} },
    .{ "IDC_HAND", .{} },
    .{ "IDC_APPSTARTING", .{} },
    .{ "IDC_HELP", .{} },
    .{ "IDC_PIN", .{} },
    .{ "IDC_PERSON", .{} },

    //.{ "IDI_APPLICATION", .{} }, This one is aligned so we can generate it
    .{ "IDI_HAND", .{} },
    .{ "IDI_QUESTION", .{} },
    .{ "IDI_EXCLAMATION", .{} },
    .{ "IDI_ASTERISK", .{} },
    .{ "IDI_WINLOGO", .{} },
    .{ "IDI_SHIELD", .{} },

    // HWND_DESKTOP and HWND_TOP are HWND types, but they are 0 so they need to be ?HWND
    .{ "HWND_DESKTOP", .{} },
    .{ "HWND_TOP", .{} },
});
fn generateConstant(sdk_file: *SdkFile, writer: *CodeWriter, constant_obj: json.ObjectMap) !void {
    try jsonObjEnforceKnownFieldsOnly(constant_obj, &[_][]const u8 {"Name", "Type", "Value", "ValueType", "Attrs"}, sdk_file);
    const name_tmp = (try jsonObjGetRequired(constant_obj, "Name", sdk_file)).String;
    const type_ref = (try jsonObjGetRequired(constant_obj, "Type", sdk_file)).Object;
    const value_type_str = (try jsonObjGetRequired(constant_obj, "ValueType", sdk_file)).String;
    const value_node = try jsonObjGetRequired(constant_obj, "Value", sdk_file);

    const attrs_node = (try jsonObjGetRequired(constant_obj, "Attrs", sdk_file)).Array;
    _ = attrs_node; // TODO: handle Attrs

    const name_pool = try global_symbol_pool.add(name_tmp);
    try sdk_file.const_exports.append(name_pool);

    const value_type = global_value_type_map.get(value_type_str) orelse {
        std.log.err("unknown ValueType '{s}'", .{value_type_str});
        return error.AlreadyReported;
    };

    if (constants_to_skip.get(name_pool.slice)) |_| {
        try writer.linef("// skipped '{}'", .{name_pool});
        return;
    }
    const zig_type_formatter = try addTypeRefs(sdk_file, ArchFlags.all, type_ref, .{
        .reason = .direct_type_access, .is_const = true, .in = false, .out = false, .anon_types = null, .null_modifier = 0 }, null);

    const kind = (jsonObjGetRequired(type_ref, "Kind", sdk_file) catch unreachable).String;
    if (std.mem.eql(u8, kind, "Native")) {
        jsonEnforce(value_type != .PropertyKey);
        jsonObjEnforceKnownFieldsOnly(type_ref, &[_][]const u8 {"Kind", "Name"}, sdk_file) catch unreachable;
        const name = (jsonObjGetRequired(type_ref, "Name", sdk_file) catch unreachable).String;
        const native_type = global_native_type_map.get(name) orelse std.debug.panic("unknown Native type '{s}'", .{name});
        if (native_type == .Guid) {
            try writer.linef("pub const {s} = Guid.initString({});", .{name_pool, fmtConstValue(value_type, value_node, sdk_file)});
        } else {
            try writer.linef("pub const {s} = {};", .{name_pool, fmtConstValue(value_type, value_node, sdk_file)});
        }
    } else {
        if (value_type == .PropertyKey) {
            const value_obj = switch (value_node) {
                .Object => |obj| obj,
                else => jsonPanicMsg("expected PropertyKey to be an object but got: {s}", .{fmtJson(value_node)}),
            };
            try jsonObjEnforceKnownFieldsOnly(value_obj, &[_][]const u8 {"Fmtid", "Pid"}, sdk_file);
            const fmtid = (try jsonObjGetRequired(value_obj, "Fmtid", sdk_file)).String;
            const pid = (try jsonObjGetRequired(value_obj, "Pid", sdk_file)).Integer;
            try writer.writef("pub const {s} = ", .{name_pool}, .{.nl=false});
            try generateTypeRef(sdk_file, writer, zig_type_formatter);
            try writer.writef(" {{ .fmtid = @import(\"{s}zig.zig\").Guid.initString(\"{s}\"), .pid = {} }};", .{
                sdk_file.getWin32DirImportPrefix(),
                fmtid,
                pid
            }, .{.start=.mid});
        } else {
            try writer.writef("pub const {s} = @import(\"{s}zig.zig\").typedConst(", .{
                name_pool,
                sdk_file.getWin32DirImportPrefix(),
            }, .{.nl=false});
            try generateTypeRef(sdk_file, writer, zig_type_formatter);
            try writer.writef(", {});", .{
                fmtConstValue(value_type, value_node, sdk_file),
            }, .{.start=.mid});
        }
    }
}

// workaround https://github.com/microsoft/win32metadata/issues/389
const also_usable_type_api_map = std.ComptimeStringMap([]const u8, .{
    .{ "HDC", "Graphics.Gdi" },
    .{ "HGDIOBJ", "Graphics.Gdi" },
    .{ "HICON", "UI.WindowsAndMessaging" },
    .{ "HANDLE", "System.SystemServices" },
    .{ "HeapHandle", "System.SystemServices" },
});

const Depth = u3;

const CodeWriter = struct {
    writer: std.fs.File.Writer,
    depth: u4,
    midline: bool,

    pub fn writeBlock(self: CodeWriter, comptime s: []const u8) !void {
        std.debug.assert(s[s.len-1] == '\n');
        std.debug.assert(self.depth == 0);
        std.debug.assert(!self.midline);
        try self.writer.writeAll(s);
    }

    pub const LineOpt = struct {
        start: enum { line, any, mid } = .line,
        nl: bool = true,
    };
    pub fn writef(self: *CodeWriter, comptime fmt: []const u8, args: anytype, comptime opt: LineOpt) !void {
        std.debug.assert(null == std.mem.indexOf(u8, fmt, "\n"));
        const do_indent = blk: { switch (opt.start) {
            .line => {
                std.debug.assert(!self.midline);
                break :blk true;
            },
            .any => break :blk !self.midline,
            .mid => {
                std.debug.assert(self.midline);
                break :blk false;
            },
        }};
        if (do_indent) {
            var i: @TypeOf(self.depth) = 0;
            while (i < self.depth) : (i += 1) {
                try self.writer.writeAll("    ");
            }
            self.midline = true;
        }
        if (@typeInfo(@TypeOf(args)).Struct.fields.len == 0) {
            try self.writer.writeAll(fmt ++ (if (opt.nl) "\n" else ""));
        } else {
            try self.writer.print(fmt ++ (if (opt.nl) "\n" else ""), args);
        }
        self.midline = !opt.nl;
    }

    pub fn write(self: *CodeWriter, comptime s: []const u8, comptime opt: LineOpt) !void {
        try self.writef(s, .{}, opt);
    }
    pub fn line(self: *CodeWriter, comptime s: []const u8) !void {
        try self.writef(s, .{}, .{});
    }
    pub fn linef(self: *CodeWriter, comptime fmt: []const u8, args: anytype) !void {
        try self.writef(fmt, args, .{});
    }
};

fn generateType(sdk_file: *SdkFile, writer: *CodeWriter, type_obj: json.ObjectMap, enum_alias_conflicts: *StringPool.HashMap(StringPool.Val)) !void {
    const kind = (try jsonObjGetRequired(type_obj, "Kind", sdk_file)).String;
    const tmp_name = (try jsonObjGetRequired(type_obj, "Name", sdk_file)).String;
    const arches = ArchFlags.initJson((try jsonObjGetRequired(type_obj, "Architectures", sdk_file)).Array.items);

    if (std.mem.eql(u8, kind, "ComClassID")) {
        if (arches.flags != ArchFlags.all.flags)
           jsonPanicMsg("not impl", .{});
        try jsonObjEnforceKnownFieldsOnly(type_obj, &[_][]const u8 {"Name", "Platform", "Architectures", "Kind", "Guid"}, sdk_file);
        const platform_node = try jsonObjGetRequired(type_obj, "Platform", sdk_file);
        const guid = (try jsonObjGetRequired(type_obj, "Guid", sdk_file)).String;
        const clsid_pool = try global_symbol_pool.addFormatted("CLSID_{s}", .{tmp_name});
        try generatePlatformComment(writer, platform_node);
        try writer.linef("const {s}_Value = @import(\"{s}zig.zig\").Guid.initString(\"{s}\");", .{clsid_pool, sdk_file.getWin32DirImportPrefix(), guid});
        try writer.linef("pub const {s} = &{0s}_Value;", .{clsid_pool});
        try sdk_file.const_exports.append(clsid_pool);
        return;
    }

    const pool_name = try global_symbol_pool.add(tmp_name);
    //
    // TODO: add 'ArchFlags' to type_exports?
    //
    if (arches.flags == ArchFlags.all.flags) {
        std.debug.assert(sdk_file.type_exports.get(pool_name) == null);
        try sdk_file.type_exports.put(pool_name, .{});
    } else {
        try generateArchPrefix(writer, sdk_file.depth, arches, "pub ");
    }
    defer {
        if (arches.flags != ArchFlags.all.flags) generateArchSuffix(writer);
    }

    if (types_that_conflict_with_consts.get(tmp_name)) |_| {
        try writer.line("// WARNING: this type symbol conflicts with a const!");
        try writer.linef("pub const {s}_CONFLICT_ = usize;", .{tmp_name});
    } else if (types_to_skip.get(tmp_name)) |_| {
        try writer.line("// TODO: not generating this type because it is causing some sort of error");
        try writer.linef("pub const {s} = usize;", .{tmp_name});
    } else if (std.mem.eql(u8, kind, "NativeTypedef")) {
        try jsonObjEnforceKnownFieldsOnly(type_obj, &[_][]const u8 {"Name", "Platform", "Architectures",
            "AlsoUsableFor", "Kind", "Def", "FreeFunc"}, sdk_file);
        const platform_node = try jsonObjGetRequired(type_obj, "Platform", sdk_file);
        const also_usable_for_node = try jsonObjGetRequired(type_obj, "AlsoUsableFor", sdk_file);
        const def_type = (try jsonObjGetRequired(type_obj, "Def", sdk_file)).Object;
        const optional_free_func : ?[]const u8 = switch (try jsonObjGetRequired(type_obj, "FreeFunc", sdk_file)) {
            .Null => null,
            .String => |s| s,
            else => jsonPanic(),
        };
        try generatePlatformComment(writer, platform_node);
        if (optional_free_func) |free_func| {
            try writer.linef("// TODO: this type has a FreeFunc '{s}', what can Zig do with this information?", .{free_func});
        }

        // HANDLE PSTR and PWSTR specially because win32metadata is not properly declaring them as arrays, only pointers
        // not sure if this is a real issue with the metadata or intentional
        const special : enum { pstr, pwstr, other } = blk: {
            if (std.mem.eql(u8, tmp_name, "PSTR")) break :blk .pstr;
            if (std.mem.eql(u8, tmp_name, "PWSTR")) break :blk .pwstr;
            break :blk .other;
        };
        if (special == .pstr or special == .pwstr) {
            //
            // verify the definition is what we expect, if not, we might be able to remove out workaround
            //
            const def_kind = (try jsonObjGetRequired(def_type, "Kind", sdk_file)).String;
            jsonEnforceMsg(std.mem.eql(u8, def_kind, "PointerTo"), "definition of {s} has changed! (Def.Kind != PointerTo, it is {s})", .{tmp_name, def_kind});
            try jsonObjEnforceKnownFieldsOnly(def_type, &[_][]const u8 {"Kind", "Child"}, sdk_file);
            const child_type = (try jsonObjGetRequired(def_type, "Child", sdk_file)).Object;
            const child_kind = (try jsonObjGetRequired(child_type, "Kind", sdk_file)).String;
            jsonEnforceMsg(std.mem.eql(u8, child_kind, "Native"), "definition of {s} has changed! (Def.Child.Kind != Native", .{tmp_name});
            try jsonObjEnforceKnownFieldsOnly(child_type, &[_][]const u8 {"Kind", "Name"}, sdk_file);
            const child_native_name = (try jsonObjGetRequired(child_type, "Name", sdk_file)).String;
            // TODO: is something is referencing PSTR or PWSTR and is NotNullTerm, then
            //       maybe I'll do something like @import("zig.zig").NotNullTerm(PSTR)
            const native_type = global_native_type_map.get(child_native_name) orelse jsonPanic();
            switch (native_type) {
                .Byte => {
                    jsonEnforce(special == .pstr);
                    try writer.line("pub const PSTR = [*:0]u8;");
                },
                .Char => {
                    jsonEnforce(special == .pwstr);
                    try writer.line("pub const PWSTR = [*:0]u16;");
                },
                else => jsonPanic(),
            }
            return;
        }

        switch (also_usable_for_node) {
            .String => |also_usable_for| {
                if (also_usable_type_api_map.get(also_usable_for)) |api| {
                    try sdk_file.addApiImport(arches, also_usable_for, api, json.Array { .items = &[_]json.Value{}, .capacity = 0, .allocator = allocator });
                    try writer.linef("//TODO: type '{s}' is \"AlsoUsableFor\" '{s}' which means this type is implicitly", .{tmp_name, also_usable_for});
                    try writer.linef("//      convertible to '{s}' but not the other way around.  I don't know how to do this", .{also_usable_for});
                    try writer.line("//      in Zig so for now I'm just defining it as an alias");
                    try writer.linef("pub const {s} = {s};", .{tmp_name, also_usable_for});
                    //try writer.linef("pub const {s} = extern struct {{ base: {s} }};", .{tmp_name, also_usable_for});
                } else std.debug.panic("AlsoUsableFor type '{s}' is missing from alsoUsableForApiMap", .{also_usable_for});
                return;
            },
            .Null => {},
            else => jsonPanic(),
        }

        // NOTE: for now, I'm just hardcoding a few types to redirect to the ones defined in 'std'
        //       this allows apps to use values of these types interchangeably with bindings in std
        if (@import("handletypes.zig").std_handle_types.get(tmp_name)) |std_sym| {
            try writer.linef("pub const {s} = @import(\"std\").{s};", .{tmp_name, std_sym});
            return;
        }
        // workaround https://github.com/microsoft/win32metadata/issues/395
        if (@import("handletypes.zig").handle_types.get(tmp_name)) |_| {
            try writer.linef("pub const {s} = *opaque{{}};", .{tmp_name});
            return;
        }

        // TODO: set is_const, in and out properly
        const zig_type_formatter = try addTypeRefs(sdk_file, arches, def_type, .{
            .reason = .direct_type_access, .is_const = false, .in = false, .out = false, .anon_types = null, .null_modifier = 0 }, null);
        try writer.writef("pub const {s} = ", .{tmp_name}, .{.nl=false});
        try generateTypeRef(sdk_file, writer, zig_type_formatter);
        try writer.write(";", .{.start=.mid});
    } else if (std.mem.eql(u8, kind, "Enum")) {
        try generateEnum(sdk_file, writer, type_obj, pool_name, enum_alias_conflicts);
    } else if (std.mem.eql(u8, kind, "Union")) {
        try generateStructOrUnion(sdk_file, writer, type_obj, arches, pool_name, .Union, null);
    } else if (std.mem.eql(u8, kind, "Struct")) {
        try generateStructOrUnion(sdk_file, writer, type_obj, arches, pool_name, .Struct, null);
    } else if (std.mem.eql(u8, kind, "FunctionPointer")) {
        if (func_ptr_dependency_loop_problems.get(tmp_name)) |_| {
            try writer.line("// TODO: this function pointer causes dependency loop problems, so it's stubbed out");
            try writer.linef("pub const {s} = fn() callconv(@import(\"std\").os.windows.WINAPI) void;", .{tmp_name});
            return;
        }
        try generateFunction(sdk_file, writer, type_obj, .ptr, null, null);
        try sdk_file.tmp_func_ptr_workaround_list.append(pool_name);
    } else if (std.mem.eql(u8, kind, "Com")) {
        try generateCom(sdk_file, writer, type_obj, arches, pool_name);
    } else {
        jsonPanicMsg("{s}: unknown type Kind '{s}'", .{sdk_file.json_basename, kind});
    }
}

const types_to_skip = std.ComptimeStringMap(Nothing, .{
    // error: array of 'win32.ui.shell.FILEDESCRIPTORA' not allowed in packed struct due to padding bits
    .{ "FILEGROUPDESCRIPTORA", .{} },
});
const types_that_conflict_with_consts = std.ComptimeStringMap(Nothing, .{
    // This symbol conflicts with a constant with the exact same name
    .{ "AE_SRVSTATUS", .{} },
    .{ "AE_SESSLOGON", .{} },
    .{ "AE_SESSLOGOFF", .{} },
    .{ "AE_SESSPWERR", .{} },
    .{ "AE_CONNSTART", .{} },
    .{ "AE_CONNSTOP", .{} },
    .{ "AE_CONNREJ", .{} },
    .{ "AE_RESACCESS", .{} },
    .{ "AE_RESACCESSREJ", .{} },
    .{ "AE_CLOSEFILE", .{} },
    .{ "AE_SERVICESTAT", .{} },
    .{ "AE_ACLMOD", .{} },
    .{ "AE_UASMOD", .{} },
    .{ "AE_NETLOGON", .{} },
    .{ "AE_NETLOGOFF", .{} },
    .{ "AE_LOCKOUT", .{} },
});

const com_types_to_skip = std.ComptimeStringMap(Nothing, .{
    .{ "placeholder_ignore_me", .{} },
});

fn generatePlatformComment(writer: *CodeWriter, platform_node: std.json.Value) !void {
    switch (platform_node) {
        .String => |platform| {
            try writer.linef("// TODO: this type is limited to platform '{s}'", .{platform});
        },
        .Null => {},
        else => jsonPanic(),
    }
}

const AnonTypes = struct {
    types: StringPool.HashMap(json.ObjectMap),
    pub fn init() AnonTypes {
        return .{
            .types = StringPool.HashMap(json.ObjectMap).init(allocator),
        };
    }
    pub fn deinit(self: *AnonTypes) void {
        self.types.deinit();
    }
};

fn generateStructOrUnion(sdk_file: *SdkFile, writer: *CodeWriter, type_obj: json.ObjectMap, arches: ArchFlags, pool_name: StringPool.Val, kind: ContainerKind, nested_context: ?*const NestedContext) !void {
    std.debug.assert(getAnonKind(pool_name.slice) == null);
    try jsonObjEnforceKnownFieldsOnly(type_obj, &[_][]const u8 {"Kind", "Name", "Platform", "Architectures",
        "Size", "PackingSize", "Fields", "Comment", "NestedTypes"}, sdk_file);
    const platform_node = try jsonObjGetRequired(type_obj, "Platform", sdk_file);
    try generatePlatformComment(writer, platform_node);
    try writer.writef("pub const {} = ", .{pool_name}, .{.nl=false});
    try generateStructOrUnionDef(sdk_file, writer, type_obj, arches, kind, nested_context);
    try writer.line("};");
}

fn generateStructOrUnionDef(sdk_file: *SdkFile, writer: *CodeWriter, type_obj: json.ObjectMap, arches: ArchFlags, kind: ContainerKind, nested_context: ?*const NestedContext) anyerror!void {

    const struct_size = (try jsonObjGetRequired(type_obj, "Size", sdk_file)).Integer;
    _ = struct_size; // ignored for now
    const struct_packing_size = (try jsonObjGetRequired(type_obj, "PackingSize", sdk_file)).Integer;
    const struct_fields = (try jsonObjGetRequired(type_obj, "Fields", sdk_file)).Array;
    const struct_nested_types = (try jsonObjGetRequired(type_obj, "NestedTypes", sdk_file)).Array;

    const type_mod: []const u8 = if (struct_packing_size == 1) "packed" else "extern";
    const zig_type = if (kind == .Struct) "struct" else "union";

    try writer.writef("{s} {s} {{", .{type_mod, zig_type}, .{.start=.any});
    writer.depth += 1;
    defer writer.depth -=1;

    var anon_types = AnonTypes.init();
    defer anon_types.deinit();

    const this_nested_context_data = NestedContext {
        .nested_types = struct_nested_types,
        .parent = nested_context,
    };
    const this_nested_context = if (struct_nested_types.items.len > 0) &this_nested_context_data else nested_context;

    for (struct_nested_types.items) |*nested_type_node_ptr| {
        const nested_type_obj = nested_type_node_ptr.Object;
        const nested_kind = (try jsonObjGetRequired(nested_type_obj, "Kind", sdk_file)).String;
        const nested_tmp_name = (try jsonObjGetRequired(nested_type_obj, "Name", sdk_file)).String;
        const architectures = (try jsonObjGetRequired(nested_type_obj, "Architectures", sdk_file)).Array;
        const pool_name = try global_symbol_pool.add(nested_tmp_name);
        if (getAnonKind(nested_tmp_name)) |_| {
            if (architectures.items.len > 0) // we don't handle architectures in this case
               jsonPanicMsg("not impl", .{});
            try anon_types.types.put(pool_name, nested_type_obj);
        } else {
            if (std.mem.eql(u8, nested_kind, "Union")) {
                try generateStructOrUnion(sdk_file, writer, nested_type_obj, arches, pool_name, .Union, this_nested_context);
            } else if (std.mem.eql(u8, nested_kind, "Struct")) {
                try generateStructOrUnion(sdk_file, writer, nested_type_obj, arches, pool_name, .Struct, this_nested_context);
            } else jsonPanicMsg("not impl", .{});
        }
    }

    if (struct_fields.items.len == 0) {
        try writer.line("placeholder: usize, // TODO: why is this type empty?");
    } else {
        if (struct_packing_size > 1 and kind == .Union) {
            try writer.line("// WARNING: unable to add field alignment because it's not implemented for unions");
        } else if (struct_packing_size > 1) {
            try writer.line("// WARNING: unable to add field alignment because it's causing a compiler bug");
            // Assertion failed at /home/vsts/work/1/s/src/stage1/analyze.cpp:8758 in resolve_llvm_types_struct. This is a bug in the Zig compiler.thread 3298 panic:
        }
        for (struct_fields.items) |*field_node_ptr| {
            const field_obj = field_node_ptr.Object;
            try jsonObjEnforceKnownFieldsOnly(field_obj, &[_][]const u8 {"Name", "Type", "Attrs"}, sdk_file);
            const field_name = (try jsonObjGetRequired(field_obj, "Name", sdk_file)).String;
            const field_type = (try jsonObjGetRequired(field_obj, "Type", sdk_file)).Object;
            const field_attrs = (try jsonObjGetRequired(field_obj, "Attrs", sdk_file)).Array;
            // !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
            // !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
            // TODO: implement null_modifier
            // !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
            // !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
            var field_options = TypeRefFormatter.Options { .reason = .var_decl, .anon_types = &anon_types, .null_modifier = 0 };
            for (field_attrs.items) |*attr_node_ptr| {
                const attr_str = attr_node_ptr.String;
                if (std.mem.eql(u8, attr_str, "Const")) {
                    field_options.is_const = true;
                } else if (std.mem.eql(u8, attr_str, "NotNullTerminated")) {
                    field_options.not_null_term = true;
                } else if (std.mem.eql(u8, attr_str, "NullNullTerminated")) {
                    field_options.null_null_term = true;
                } else if (std.mem.eql(u8, attr_str, "Obselete")) {
                    try writer.line("/// Deprecated");
                } else if (std.mem.eql(u8, attr_str, "Optional")) {
                    field_options.optional = true;
                } else {
                    jsonPanicMsg("unhandled custom field attribute {s}", .{attr_str});
                }
            }
            const field_type_formatter = try addTypeRefs(sdk_file, arches, field_type, field_options, this_nested_context);
            try writer.writef("{}: ", .{std.zig.fmtId(field_name)}, .{.nl=false});
            try generateTypeRef(sdk_file, writer, field_type_formatter);
            if (struct_packing_size > 1 and kind == .Struct) {
                // NOTE: this is causing a compiler bug
                //try writer.writef(" align({})", .{struct_packing_size}, .{.start=.mid,.nl=false});
            }
            try writer.write(",", .{.start=.mid});
        }
    }
}

// Not sure whether enums should be exhaustive or not, for now
// I'll default to all of them being exhaustive except the ones
// in this list that I know are currently not exhaustive.
const non_exhaustive_enums = std.ComptimeStringMap(Nothing, .{
    // This enum is not exhaustive because it is missing a value, see
    //     https://github.com/microsoft/win32metadata/issues/203
    .{ "CLSCTX", .{} },
    // SEND_FLAGS is missing the value 0
    .{ "SEND_FLAGS", .{} },
    .{ "WINDOW_LONG_PTR_INDEX", .{} },
});

fn shortEnumValueName(enum_type_name: []const u8, full_value_name: []const u8) []const u8 {
    if (full_value_name.len == 0) {
        // NOTE: this is probably a bug in the win32metadata
        return "_noname_";
    }
    const offset = init: {
        if ((full_value_name.len <= enum_type_name.len + 1) or
            (full_value_name[enum_type_name.len] != '_') or
            !std.mem.startsWith(u8, full_value_name, enum_type_name)) {
            break :init 0;
        }
        const first_c = full_value_name[enum_type_name.len+1];
        if (first_c <= '9' and first_c >= '0') {
            break :init enum_type_name.len;
        }
        break :init enum_type_name.len + 1;
    };
    return full_value_name[offset..];
}

// TODO: this is a set of enums whose value symbols conflict with other symbols
const suppress_enum_aliases = std.ComptimeStringMap(Nothing, .{
    // suppress this one because the CFE_UNDERLINE enum value alias conflicts with the name of an enum type
    .{ "CFE_EFFECTS", .{} },
    // these types have values that conflict with their own enum type name
    .{ "INTERNET_DEFAULT_PORT", .{} },
    .{ "PDH_VERSION", .{} },
    .{ "POWER_PLATFORM_ROLE_VERSION", .{} },
    // --------------------------------------------------------------------------------
    // suppress these enum value aliases because there is already a constant with the same name
    // --------------------------------------------------------------------------------
    .{ "JsRuntimeVersion", .{} },
    .{ "GetIconInfo_hicon", .{} },
    .{ "PFN_WdsCliCallback_dwMessageIdFlags", .{} },
    .{ "MIB_IPFORWARD_TYPE", .{} },
    .{ "OLEMISC", .{} },
    .{ "IMAGEHLP_CBA_EVENT_SEVERITY", .{} },
    .{ "PFN_WDS_CLI_CALLBACK_MESSAGE_ID", .{} },
    // --------------------------------------------------------------------------------
    // suppress the rest because there is another enum with the same enum value alias
    // --------------------------------------------------------------------------------
    // Security
    .{ "NCrypt_dwFlags", .{} },
    .{ "IAzClientContext3_GetGroups_ulOptionsFlags", .{} },
    .{ "NCryptNotifyChangeKey_dwFlags", .{} },
    .{ "SECPKG_ATTR_1", .{} },
    .{ "CryptImportPKCS8_dwFlags", .{} },
    .{ "NCryptDecrypt_dwFlags", .{} },
    .{ "KERB_CERTIFICATE_LOGON_MessageTypeFlags", .{} },
    .{ "SC_ACTION_TypeFlags", .{} },
    .{ "IIdentityProvider_Advise_dwIdentityUpdateEventsFlags", .{} },
    .{ "CRYPT_KEY_PROV_FLAGS", .{} },
    // WindowsProgramming
    .{ "VER_MASK", .{} },
    .{ "SetHandleInformation_dwFlags", .{} },
    .{ "DuplicateHandle_dwOptionsFlags", .{} },
    .{ "REG_OPEN_CREATE_OPTIONS", .{} },
    // SystemServices
    .{ "QueryInformationJobObject_JobObjectInformationClassFlags", .{} },
    .{ "HeapSetInformation_HeapInformationClassFlags", .{} },
    .{ "JOBOBJECT_NOTIFICATION_LIMIT_INFORMATION_2_IoRateControlToleranceInterval", .{} },
    .{ "JOBOBJECT_RATE_CONTROL_TOLERANCE_INTERVAL", .{} },
    .{ "JOBOBJECT_LIMIT_VIOLATION_INFORMATION_2_RateControlTolerance", .{} },
    .{ "JOBOBJECT_IO_RATE_CONTROL_INFORMATIONFlags", .{} },
    .{ "CreateFileMapping_flProtect", .{} },
    .{ "PFM_FLAGS", .{} },
    .{ "JOBOBJECT_BASIC_LIMIT_INFORMATIONFlags", .{} },
    .{ "JOBOBJECT_SECURITY_LIMIT_INFORMATIONFlags", .{} },
    .{ "JOBOBJECT_BASIC_UI_RESTRICTIONS_UIRestrictionsClassFlags", .{} },
    // NetManagement
    .{ "NetWkstaSetInfo_levelFlags", .{} },
    // ComponentServices
    .{ "ICOMAdminCatalog2_IsSafeToDelete_pCOMAdminInUseFlags", .{} },
    .{ "ImportUnconfiguredComponents_pVarComponentType", .{} },
    .{ "ICOMAdminCatalog_InstallApplication_lOptionsFlags", .{} },
    .{ "ICOMAdminCatalog_ExportApplication_lOptionsFlags", .{} },
    .{ "WerRegisterFile_regFileTypeFlags", .{} },
    .{ "WerReportSubmit_pSubmitResultFlags", .{} },
    .{ "WerReportCreate_repTypeFlags", .{} },
    .{ "WerReportSubmit_consentFlags", .{} },
    // FileSystem
    .{ "DefineDosDevice_dwFlags", .{} },
    .{ "CreateFile_dwShareMode", .{} },
    .{ "CreateLogFile_fCreateDispositionFlags", .{} },
    .{ "ReOpenFile_dwFlagsAndAttributes", .{} },
    // Parental Controls
    .{ "IWindowsParentalControlsCore_GetVisibility_peVisibilityFlags", .{} },
    .{ "GetRestrictions_pdwRestrictions", .{} },
    .{ "IWPCWebSettings_GetSettings_pdwSettingsFlags", .{} },
    // Gdi
    .{ "CombineRgn_iMode", .{} },
    .{ "CreateDIBitmap_iUsage", .{} },
    .{ "PatBlt_ropFlags", .{} },
    .{ "GetCurrentObject_typeFlags", .{} },
    .{ "SetROP2_rop2Flags", .{} },
    // MachineLearning
    .{ "MLOperatorTensorDataType", .{} },
    .{ "MLOperatorExecutionType", .{} },
    .{ "MLOperatorEdgeType", .{} },
    // Com
    .{ "IPropertyPageSite_OnStatusChangeFlags", .{} },
    .{ "IOleControlSite_TransformCoordsFlags", .{} },
    // ApplicationInstallationAndServicing
    .{ "LPDISPLAYVAL_uiTypeFlags", .{} },
    .{ "MsiSourceList_dwContext", .{} },
    .{ "MsiAdvertiseScript_dwFlags", .{} },
    .{ "MsiViewModify_eModifyModeFlags", .{} },
    .{ "MsiCreateTransformSummaryInfo_iErrorConditions", .{} },
    .{ "MsiCreateTransformSummaryInfo_iValidation", .{} },
    .{ "MsiEnumClientsEx_dwContext", .{} },
    // WindowsAndMessaging
    .{ "DrawIconEx_diFlags", .{} },
    // Debug
    .{ "SymGetHomeDirectory_type", .{} },
    .{ "SymGetSymbolFile_Type", .{} },
    // Multimedia
    .{ "MIDI_OPEN_TYPE", .{} },
});

const EnumValue = struct {
    pool_name: StringPool.Val,
    short_name: []const u8,
    value: json.Value,
    no_alias: bool,
    conflict_index: ?usize,
    pub fn valueIsZero(self: EnumValue) bool {
        return switch (self.value) {
            .Integer => |i| i == 0,
            else => false,
        };
    }
};
fn matchLen(a: []const u8, b: []const u8) usize {
    var i : usize = 0;
    while (i < a.len and i < b.len and a[i] == b[i]) : (i += 1) { }
    return i;
}
fn setShortNames(values: []EnumValue) void {
    var at_first = true;
    var longest_prefix_match : []const u8 = undefined;
    for (values) |*val_ref| {
        if ((
                val_ref.pool_name.eql(global_symbol_none) or
                val_ref.pool_name.eql(global_symbol_None)
            ) and
            val_ref.valueIsZero()
        ) {
            val_ref.short_name = val_ref.pool_name.slice;
            val_ref.no_alias = true;
            continue;
        }

        if (at_first) {
            longest_prefix_match = val_ref.pool_name.slice;
            at_first = false;
        } else {
            longest_prefix_match.len = matchLen(longest_prefix_match, val_ref.pool_name.slice);
        }
    }
    for (values) |*val_ref| {
        if (val_ref.no_alias)
            continue;

        if (val_ref.pool_name.slice.len == 0) {
            // TODO: this happens to snmp:AS_ANY_TYPE, it's probably a bug that should be filed
            val_ref.short_name = "__no_name__";
        } else {
            var cutoff = longest_prefix_match.len;
            if (cutoff > 0 and cutoff == val_ref.pool_name.slice.len) {
                cutoff -= 1;
            }
            val_ref.short_name = val_ref.pool_name.slice[cutoff..];
        }
    }
}

fn generateEnum(sdk_file: *SdkFile, writer: *CodeWriter, type_obj: json.ObjectMap, pool_name: StringPool.Val, enum_alias_conflicts: *StringPool.HashMap(StringPool.Val)) !void {
    try jsonObjEnforceKnownFieldsOnly(type_obj, &[_][]const u8 {"Name", "Platform", "Architectures", "Kind", "Flags", "Scoped", "Values", "IntegerBase"}, sdk_file);
    const platform_node = try jsonObjGetRequired(type_obj, "Platform", sdk_file);
    const flags = (try jsonObjGetRequired(type_obj, "Flags", sdk_file)).Bool;
    const scoped = (try jsonObjGetRequired(type_obj, "Scoped", sdk_file)).Bool;
    const json_values = (try jsonObjGetRequired(type_obj, "Values", sdk_file)).Array;
    const integer_base = switch (try jsonObjGetRequired(type_obj, "IntegerBase", sdk_file)) {
        .Null => "i32",
        .String => |s| nativeTypeToZigType(global_native_type_map.get(s) orelse {
            std.log.err("enum '{}' has an unknown IntegerBase '{s}'", .{pool_name, s});
            return error.AlreadyReported;
        }),
        else => jsonPanic(),
    };
    const values = try allocator.alloc(EnumValue, json_values.items.len);
    var values_initialized_len: usize = 0;
    defer allocator.free(values);
    for (json_values.items) |*value_node_ptr| {
        const value_obj = value_node_ptr.Object;
        try jsonObjEnforceKnownFieldsOnly(value_obj, &[_][]const u8 {"Name", "Value"}, sdk_file);
        const value_tmp_name = (try jsonObjGetRequired(value_obj, "Name", sdk_file)).String;
        values[values_initialized_len] = .{
            .pool_name = try global_symbol_pool.add(value_tmp_name),
            .short_name = "",
            .value = try jsonObjGetRequired(value_obj, "Value", sdk_file),
            .no_alias = false,
            .conflict_index = null,
        };
        values_initialized_len += 1;
    }
    setShortNames(values);

    // find conflicts
    for (values) |val, i| {
        for (values[0..i]) |other_val, j| {
            if (jsonEql(val.value, other_val.value)) {
                values[i].conflict_index = j;
                break;
            }
        }
    }

    try generatePlatformComment(writer, platform_node);
    try writer.linef("pub const {} = enum({s}) {{", .{pool_name, integer_base});
    if (values.len == 0) {
        // zig doesn't allow empty enums
        try writer.line("    _");
    } else {
        for (values) |val| {
            if (val.conflict_index) |conflict_index| {
                try writer.linef("    // {s} = {}, this enum value conflicts with {s}", .{
                    std.zig.fmtId(val.short_name), fmtJson(val.value), std.zig.fmtId(values[conflict_index].short_name)});
            } else {
                try writer.linef("    {s} = {},", .{std.zig.fmtId(val.short_name), fmtJson(val.value)});
            }
        }
        if (flags) {
            try writer.linef("    _,", .{});
        } else if (non_exhaustive_enums.get(pool_name.slice)) |_| {
            try writer.linef("    _,", .{});
        }
    }
    if (flags) {
        try writer.line("    pub fn initFlags(o: struct {");
        for (values) |val| {
            if (val.conflict_index == null) {
                try writer.linef("        {}: u1 = 0,", .{std.zig.fmtId(val.short_name)});
            }
        }
        try writer.linef("    }}) {s} {{", .{pool_name});
        try writer.linef("        return @intToEnum({s},", .{pool_name});
        var prefix: []const u8 = " ";
        for (values) |val| {
            if (val.conflict_index == null) {
                try writer.linef("            {s} (if (o.{s} == 1) @enumToInt({s}.{1s}) else 0)", .{prefix, std.zig.fmtId(val.short_name), pool_name});
                prefix = "|";
            }
        }
        try writer.line("        );");
        try writer.line("    }");
    }
    try writer.line("};");

    if (scoped) {
        try writer.linef("// NOTE: not creating aliases because this enum is 'Scoped'", .{});
        return;
    }
    if (suppress_enum_aliases.get(pool_name.slice)) |_| {
        try writer.linef("// TODO: enum '{}' has known issues with its value aliases", .{pool_name});
        return;
    }

    // create value aliases
    var alias_count: u32 = 0;
    for (values) |val| {
        if (enum_alias_conflicts.get(val.pool_name)) |existing| {
            std.debug.print("error: enum value alias '{}' is defined by 2 enum types.\n", .{val.pool_name});
            std.debug.print("       add one of the following lines to the suppress_enum_aliases list:\n", .{});
            std.debug.print("    .{{ \"{}\", .{{}} }},\n", .{existing});
            std.debug.print("    .{{ \"{}\", .{{}} }},\n", .{pool_name});
            return error.AlreadyReported;
        }
        if (val.no_alias) {
            continue;
        }
        alias_count += 1;
        try enum_alias_conflicts.put(val.pool_name, pool_name);
        try sdk_file.const_exports.append(val.pool_name);
        const target_short_name = if (val.conflict_index) |i| values[i].short_name else val.short_name;
        try writer.linef("pub const {} = {}.{};", .{val.pool_name, pool_name, std.zig.fmtId(target_short_name)});
    }
}




fn generateCom(sdk_file: *SdkFile, writer: *CodeWriter, type_obj: json.ObjectMap, arches: ArchFlags, com_pool_name: StringPool.Val) !void {
    try jsonObjEnforceKnownFieldsOnly(type_obj, &[_][]const u8 {"Kind", "Name", "Platform", "Architectures", "Guid", "Interface", "Methods"}, sdk_file);
    const platform_node = try jsonObjGetRequired(type_obj, "Platform", sdk_file);

    const com_optional_guid : ?[]const u8 = switch (try jsonObjGetRequired(type_obj, "Guid", sdk_file)) {
        .Null => null,
        .String => |s| s,
        else => jsonPanic(),
    };
    const com_optional_iface : ?json.ObjectMap = switch (try jsonObjGetRequired(type_obj, "Interface", sdk_file)) {
        .Null => null,
        .Object => |o| o,
        else => jsonPanic(),
    };
    const com_methods = (try jsonObjGetRequired(type_obj, "Methods", sdk_file)).Array;
    const skip = com_types_to_skip.has(com_pool_name.slice);
    if (skip) {
        try writer.line("// WARNING: this COM type has been skipped because it causes some sort of error");
    }
    try generatePlatformComment(writer, platform_node);

    const iid_pool = try global_symbol_pool.addFormatted("IID_{s}", .{com_pool_name.slice});
    if (com_optional_guid) |guid| {
        try writer.linef("const {s}_Value = @import(\"{s}zig.zig\").Guid.initString(\"{s}\");",
            .{ iid_pool, sdk_file.getWin32DirImportPrefix(), guid});
        try writer.linef("pub const {s} = &{0s}_Value;", .{iid_pool});
        try sdk_file.const_exports.append(iid_pool);
    }

    try writer.linef("pub const {s} = extern struct {{", .{com_pool_name});
    try writer.line("    pub const VTable = extern struct {");
    var iface_formatter : TypeRefFormatter = undefined;

    if (skip) {
        try writer.line("        _: *opaque{}, // just a placeholder because this COM type is skipped");
    } else {
        if (com_optional_iface) |iface| {
            iface_formatter = try addTypeRefs(sdk_file, arches, iface, .{ .reason = .direct_type_access, .anon_types = null, .null_modifier = 0 }, null);
            try writer.write("        base: ", .{.nl=false});
            try generateTypeRef(sdk_file, writer, iface_formatter);
            try writer.write(".VTable,", .{.start=.mid});
        }

        // some COM objects have methods with the same name and only differ in parameter types
        var method_conflicts = StringHashMap(u8).init(allocator);
        defer method_conflicts.deinit();

        for (com_methods.items) |*method_node_ptr| {
            const method_name = (try jsonObjGetRequired(method_node_ptr.Object, "Name", sdk_file)).String;
            const count = method_conflicts.get(method_name) orelse 0;
            try method_conflicts.put(method_name, count + 1);
            try generateFunction(sdk_file, writer, method_node_ptr.Object, .com, if (count == 0) null else count, com_pool_name.slice);
        }
    }

    try writer.line("    };");
    try writer.linef("    vtable: *const VTable,", .{});

    // some COM objects have methods with the same name and only differ in parameter types
    var method_conflicts = StringHashMap(u8).init(allocator);
    defer method_conflicts.deinit();

    // Generate wrapper methods for every entry in the vtable
    try writer.line("    pub fn MethodMixin(comptime T: type) type { return struct {");
    if (!skip) {
        if (com_optional_iface) |_| {
            // For now we're putting this inside a sub-struct to avoid name conflicts
            try writer.write("        pub usingnamespace ", .{.nl=false});
            try generateTypeRef(sdk_file, writer, iface_formatter);
            try writer.write(".MethodMixin(T);", .{.start=.mid});
        }
        for (com_methods.items) |*method_node_ptr| {
            const method_obj = method_node_ptr.Object;
            const method_name = (try jsonObjGetRequired(method_obj, "Name", sdk_file)).String;
            const return_type = (try jsonObjGetRequired(method_obj, "ReturnType", sdk_file)).Object;
            const params = (try jsonObjGetRequired(method_obj, "Params", sdk_file)).Array;

            const count = method_conflicts.get(method_name) orelse 0;
            try method_conflicts.put(method_name, count + 1);

            try writer.line("        // NOTE: method is namespaced with interface name to avoid conflicts for now");
            try writer.writef("        pub fn {s}_{s}", .{com_pool_name, method_name}, .{.nl=false});
            if (count > 0) {
                try writer.writef("{}", .{count}, .{.start=.mid,.nl=false});
            }
            try writer.write("(self: *const T", .{.start=.mid,.nl=false});
            for (params.items) |*param_node_ptr| {
                const param_obj = param_node_ptr.Object;
                try jsonObjEnforceKnownFieldsOnly(param_obj, &[_][]const u8 {"Name", "Type", "Attrs"}, sdk_file);
                const param_name = (try jsonObjGetRequired(param_obj, "Name", sdk_file)).String;
                const param_type = (try jsonObjGetRequired(param_obj, "Type", sdk_file)).Object;
                // !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
                // !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
                // TODO: set null_modifier properly
                // !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
                // !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
                const null_modifier = 0;
                const param_options = processParamAttrs((try jsonObjGetRequired(param_obj, "Attrs", sdk_file)).Array, .var_decl, null_modifier, sdk_file);
                // NOTE: don't need to call addTypeRefs because it was already called in generateFunction above
                const param_type_formatter = fmtTypeRef(param_type, arches, param_options, null);
                if (param_options.optional_bytes_param_index) |bytes_param_index| {
                    _ = bytes_param_index; // NOTE: can't print this because we are currently inline
                    //try writer.linef("// TODO: what to do with BytesParamIndex {}?", .{bytes_param_index});
                }
                try writer.writef(", {s}: ", .{fmtParamId(param_name, sdk_file.param_names_to_avoid_map_get_fn)}, .{.start=.mid,.nl=false});
                try generateTypeRef(sdk_file, writer, param_type_formatter);
            }
            // NOTE: don't need to call addTypeRefs because it was already called in generateFunction above
            // TODO: set is_const, in and out properly
            // !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
            // !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
            // TODO: set null_modifier properly
            // !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
            // !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
            const return_type_formatter = fmtTypeRef(return_type, arches, .{
                .reason = .var_decl, .is_const = false, .in = false, .out = false, .anon_types = null, .null_modifier = 0 }, null);
            try writer.write(") callconv(.Inline) ", .{.start=.mid,.nl=false});
            try generateTypeRef(sdk_file, writer, return_type_formatter);
            try writer.write(" {", .{.start=.mid});
            try writer.writef("            return @ptrCast(*const {s}.VTable, self.vtable).{s}(@ptrCast(*const {0s}, self)", .{com_pool_name, std.zig.fmtId(method_name)}, .{.nl=false});
            for (params.items) |*param_node_ptr| {
                const param_obj = param_node_ptr.Object;
                const param_name = (try jsonObjGetRequired(param_obj, "Name", sdk_file)).String;
                try writer.writef(", {s}", .{fmtParamId(param_name, sdk_file.param_names_to_avoid_map_get_fn)}, .{.start=.mid,.nl=false});
            }
            try writer.write(");", .{.start=.any});
            try writer.line("        }");
        }
    }
    try writer.line("    };}");
    try writer.line("    pub usingnamespace MethodMixin(@This());");
    try writer.line("};");
}

fn processParamAttrs(attrs: json.Array, reason: TypeRefFormatter.Reason, null_modifier: NullModifier, sdk_file: *const SdkFile) TypeRefFormatter.Options {
    var opts = TypeRefFormatter.Options { .reason = reason, .anon_types = null, .null_modifier = null_modifier };
    for (attrs.items) |*attr_node_ptr| {
        switch (attr_node_ptr.*) {
            .Object => |attr_obj| {
                const kind = (try jsonObjGetRequired(attr_obj, "Kind", sdk_file)).String;
                if (std.mem.eql(u8, kind, "MemorySize")) {
                    try jsonObjEnforceKnownFieldsOnly(attr_obj, &[_][]const u8 {"Kind", "BytesParamIndex"}, sdk_file);
                    opts.optional_bytes_param_index = @intCast(i16, (try jsonObjGetRequired(attr_obj, "BytesParamIndex", sdk_file)).Integer);
                } else if (std.mem.eql(u8, kind, "FreeWith")) {
                    try jsonObjEnforceKnownFieldsOnly(attr_obj, &[_][]const u8 {"Kind", "Func"}, sdk_file);
                    const func = (try jsonObjGetRequired(attr_obj, "Func", sdk_file)).String;
                    _ = func; // TODO: what to do with this?
                } else jsonPanicMsg("unknown param attr Kind '{s}'", .{kind});
            },
            .String => |attr_str| {
                if (std.mem.eql(u8, attr_str, "Const")) {
                    opts.is_const = true;
                } else if (std.mem.eql(u8, attr_str, "In")) {
                    opts.in = true;
                } else if (std.mem.eql(u8, attr_str, "Out")) {
                    opts.out = true;
                } else if (std.mem.eql(u8, attr_str, "Optional")) {
                    opts.optional = true;
                } else if (std.mem.eql(u8, attr_str, "RetVal")) {
                    opts.ret_val = true;
                } else if (std.mem.eql(u8, attr_str, "NotNullTerminated")) {
                    opts.not_null_term = true;
                } else if (std.mem.eql(u8, attr_str, "NullNullTerminated")) {
                    opts.null_null_term = true;
                } else if (std.mem.eql(u8, attr_str, "ComOutPtr")) {
                    opts.com_out_ptr = true;
                } else if (std.mem.eql(u8, attr_str, "DoNotRelease")) {
                    opts.do_not_release = true;
                } else if (std.mem.eql(u8, attr_str, "Reserved")) {
                    opts.reserved = true;
                } else {
                    jsonPanicMsg("unhandled custom param attribute '{s}'", .{attr_str});
                }
            },
            else => jsonPanic(),
        }
    }
    return opts;
}

// Skip these function pointers to workaround: https://github.com/ziglang/zig/issues/4476
const func_ptr_dependency_loop_problems = std.ComptimeStringMap(Nothing, .{
    .{ "FREEOBJPROC", .{} },
    .{ "LPDDHAL_WAITFORVERTICALBLANK", .{} },
});

const funcs_with_issues = std.ComptimeStringMap(Nothing, .{
    // These functions don't work yet because Zig doesn't support the 16-byte Guid struct in the C ABI yet
    // See: https://github.com/ziglang/zig/issues/1481
    .{ "CorePrinterDriverInstalledA", .{} },
    .{ "CorePrinterDriverInstalledW", .{} },
    // workaround https://github.com/microsoft/win32metadata/issues/520
    .{ "AuthzInitializeResourceManagerEx", .{} },
    // The 3rd parameter "ObjectType" is "Optional" but is typed as an enum?
    // but the docs says it's a pointer?? wtf is going on with this one?
    .{ "BuildTrusteeWithObjectsAndNameA", .{} },
    .{ "BuildTrusteeWithObjectsAndNameW", .{} },
    // these functions contain invalid optional types (https://github.com/microsoft/win32metadata/issues/519)
    .{ "NCryptOpenKey", .{} },
    .{ "NCryptTranslateHandle", .{} },
    .{ "CryptSignAndEncodeCertificate", .{} },
    .{ "MFPCreateMediaPlayer", .{} },
    .{ "QOSRemoveSocketFromFlow", .{} },
    .{ "PrjUpdateFileIfNeeded", .{} },
    .{ "PrjDeleteFile", .{} },
    .{ "JetSetSystemParameterA", .{} },
    .{ "JetSetSystemParameterW", .{} },
    .{ "MsiGetComponentPathExA", .{} },
    .{ "MsiGetComponentPathExW", .{} },
    .{ "SymLoadModuleEx", .{} },
    .{ "SymLoadModuleExW", .{} },
    .{ "PssDuplicateSnapshot", .{} },
});
const noreturn_funcs = std.ComptimeStringMap(Nothing, .{
    .{ "ExitProcess", .{} },
});

const FuncPtrKind = enum { ptr, fixed, com };

fn generateArchPrefix(writer: *CodeWriter, module_depth: u2, arches: ArchFlags, prefix: []const u8) !void {
    std.debug.assert(arches.flags != ArchFlags.all.flags);
    try writer.linef("{s}usingnamespace switch (@import(\"{s}zig.zig\").arch) {{", .{prefix, import_prefix_table[module_depth]});
    var case_prefix: []const u8 = "";
    inline for (std.meta.fields(Arch)) |arch_field| {
        const arch = @field(Arch, arch_field.name);
        if ((arches.flags & getFlag(arch).flags) != 0) {
            try writer.writef("{s}.{s}", .{case_prefix, @tagName(arch)}, .{.start=.any, .nl=false});
            case_prefix = ", ";
        }
    }
    try writer.write(" => struct {", .{.start = .any});
    try writer.line("");
}
fn generateArchSuffix(writer: *CodeWriter) void {
    writer.line("") catch @panic("here");
    writer.line("}, else => struct { } };") catch @panic("here");
}

const ParamModifierSet = struct {
    const max_params = 30;
    ret: NullModifier = 0,
    params: [max_params]NullModifier = [_]NullModifier { 0 } ** max_params,
};

fn generateFunction(sdk_file: *SdkFile, writer: *CodeWriter, function_obj: json.ObjectMap, func_kind: FuncPtrKind, suffix: ?u8, optional_self_type: ?[]const u8) !void {
    const prefix = if (func_kind == .com) "        " else "";
    switch (func_kind) {
        .fixed => try jsonObjEnforceKnownFieldsOnly(function_obj, &[_][]const u8 {"Name", "Platform", "Architectures",
            "SetLastError", "DllImport", "ReturnType", "ReturnAttrs", "Attrs", "Params"}, sdk_file),
        .ptr, .com => try jsonObjEnforceKnownFieldsOnly(function_obj, &[_][]const u8 {"Kind", "Name", "Platform", "Architectures",
            "SetLastError", "ReturnType", "ReturnAttrs", "Attrs", "Params"}, sdk_file),
    }

    const func_name_tmp = (try jsonObjGetRequired(function_obj, "Name", sdk_file)).String;
    const platform_node = try jsonObjGetRequired(function_obj, "Platform", sdk_file);
    const arches = ArchFlags.initJson((try jsonObjGetRequired(function_obj, "Architectures", sdk_file)).Array.items);
    const set_last_error = (try jsonObjGetRequired(function_obj, "SetLastError", sdk_file)).Bool;
    _ = set_last_error; // ignored for now
    const dll_import = if (func_kind == .fixed) (try jsonObjGetRequired(function_obj, "DllImport", sdk_file)).String else "";
    const return_type = (try jsonObjGetRequired(function_obj, "ReturnType", sdk_file)).Object;
    const return_attrs = (try jsonObjGetRequired(function_obj, "ReturnAttrs", sdk_file)).Array;
    const attrs = (try jsonObjGetRequired(function_obj, "Attrs", sdk_file)).Array;
    const params = (try jsonObjGetRequired(function_obj, "Params", sdk_file)).Array;

    var notnull_set = ParamModifierSet { };

    if (func_kind == .fixed or func_kind == .ptr) {
        const pool_name = try global_symbol_pool.add(func_name_tmp);
        if (func_kind == .fixed) {
            try sdk_file.func_exports.put(pool_name, .{});
        }
        if (sdk_file.not_null_funcs.get(pool_name.slice)) |notnull_node| {
            try sdk_file.not_null_funcs_applied.put(pool_name, .{});
            jsonEnforce(notnull_node.Array.items.len > 0);
            notnull_set.ret = @intCast(NullModifier, notnull_node.Array.items[0].Integer);
            for (notnull_node.Array.items[1..]) |item, i| {
                jsonEnforce(i < notnull_set.params.len); // if we hit this, increase max param count
                jsonEnforce(i < params.items.len);
                notnull_set.params[i] = @intCast(NullModifier, item.Integer);
            }
        }
    }

    if (arches.flags != ArchFlags.all.flags) {
        // is COM supposed to support arch specific methods?
        std.debug.assert(func_kind != .com);
        try generateArchPrefix(writer, sdk_file.depth, arches, "pub ");
    }
    defer {
        if (arches.flags != ArchFlags.all.flags) generateArchSuffix(writer);
    }

    for (attrs.items) |attr_node| {
        switch (attr_node) {
            .String => |attr| {
                if (std.mem.eql(u8, attr, "SpecialName")) {
                    try writer.linef("{s}// TODO: this function has a \"SpecialName\", should Zig do anything with this?", .{prefix});
                } else jsonPanic();
            },
            else => jsonPanic(),
        }
    }
    try generatePlatformComment(writer, platform_node);
    if (funcs_with_issues.get(func_name_tmp)) |_| {
        try writer.linef("{s}// This function from dll '{s}' is being skipped because it has some sort of issue", .{prefix, dll_import});
        try writer.linef("{s}pub fn {s}() void {{ @panic(\"this function is not working\"); }}", .{prefix, func_name_tmp});
        return;
    }

    switch (func_kind) {
        .fixed => {
            jsonEnforce(suffix == null);
            try writer.linef("{s}pub extern \"{s}\" fn {s}(", .{prefix, dll_import, std.zig.fmtId(func_name_tmp)});
        },
        .ptr => {
            jsonEnforce(suffix == null);
            try writer.linef("{s}pub const {s} = fn(", .{prefix, std.zig.fmtId(func_name_tmp)});
        },
        .com => {
            if (suffix) |s| {
                try writer.writef("{s}{s}{}", .{prefix, func_name_tmp, s}, .{.nl=false});
            } else {
                try writer.writef("{s}{s}", .{prefix, std.zig.fmtId(func_name_tmp)}, .{.nl=false});
            }
            try writer.write(": fn(", .{.start=.mid});
        },
    }
    if (optional_self_type) |self_type| {
        try writer.linef("{s}    self: *const {s},", .{prefix, self_type});
    }

    for (params.items) |*param_node_ptr, i| {
        const param_obj = param_node_ptr.Object;
        try jsonObjEnforceKnownFieldsOnly(param_obj, &[_][]const u8 {"Name", "Type", "Attrs"}, sdk_file);
        const param_name = (try jsonObjGetRequired(param_obj, "Name", sdk_file)).String;
        const param_type = (try jsonObjGetRequired(param_obj, "Type", sdk_file)).Object;
        const null_modifier = notnull_set.params[i];
        const param_options = processParamAttrs((try jsonObjGetRequired(param_obj, "Attrs", sdk_file)).Array, .var_decl, null_modifier, sdk_file);
        const param_type_formatter = try addTypeRefs(sdk_file, arches, param_type, param_options, null);
        if (param_options.optional_bytes_param_index) |bytes_param_index| {
            try writer.linef("{s}    // TODO: what to do with BytesParamIndex {}?", .{prefix, bytes_param_index});
        }
        try writer.writef("{s}    {s}: ", .{prefix, std.zig.fmtId(param_name)}, .{.nl=false});
        try generateTypeRef(sdk_file, writer, param_type_formatter);
        try writer.write(",", .{.start=.mid});
    }

    try writer.writef("{s}) callconv(@import(\"std\").os.windows.WINAPI) ", .{prefix}, .{.nl=false});
    if (noreturn_funcs.get(func_name_tmp)) |_| {
        try writer.write("noreturn", .{.start=.mid,.nl=false});
    } else {
        // TODO: set is_const, in and out properly
        const return_opts = processParamAttrs(return_attrs, .var_decl, notnull_set.ret, sdk_file);
        const return_type_formatter = try addTypeRefs(sdk_file, arches, return_type, return_opts, null);
        try generateTypeRef(sdk_file, writer, return_type_formatter);
    }
    const term = if (func_kind == .com) "," else ";";
    try writer.writef("{s}", .{term}, .{.start=.mid});
}

fn generateUnicodeAliases(sdk_file: *SdkFile, writer: *CodeWriter, unicode_aliases: []json.Value) !void {
    try writer.linef   ("pub usingnamespace switch (@import(\"{s}zig.zig\").unicode_mode) {{", .{sdk_file.getWin32DirImportPrefix()});
    try writer.line    ("    .ansi => struct {");
    for (unicode_aliases) |*alias_node_ptr| {
        try writer.linef("        pub const {s} = {0s}A;", .{alias_node_ptr.String});
    }
    try writer.line("    },");
    try writer.line("    .wide => struct {");
    for (unicode_aliases) |*alias_node_ptr| {
        try writer.linef("        pub const {s} = {0s}W;", .{alias_node_ptr.String});
    }
    try writer.line("    },");
    try writer.line("    .unspecified => if (@import(\"builtin\").is_test) struct {");
    for (unicode_aliases) |*alias_node_ptr| {
        try writer.linef("        pub const {s} = *opaque{{}};", .{alias_node_ptr.String});
    }
    try writer.line("    } else struct {");
    for (unicode_aliases) |*alias_node_ptr| {
        try writer.linef("        pub const {s} = @compileError(\"'{0s}' requires that UNICODE be set to true or false in the root module\");", .{alias_node_ptr.String});
    }
    try writer.line("    },");
    try writer.line("};");
}

const Arch = enum { X86, X64, Arm64 };
const arch_name_map = std.ComptimeStringMap(Arch, .{
    .{ "X86", Arch.X86 },
    .{ "X64", Arch.X64 },
    .{ "Arm64", Arch.Arm64 },
});
pub fn getFlag(arch: Arch) ArchFlags {
    return switch (arch) {
        .X86 => ArchFlags.X86,
        .X64 => ArchFlags.X64,
        .Arm64 => ArchFlags.Arm64,
    };
}
const ArchFlags = struct {
    pub const X86 = ArchFlags { .flags = 0x01 };
    pub const X64 = ArchFlags { .flags = 0x02 };
    pub const Arm64 = ArchFlags { .flags = 0x04 };
    pub const all = ArchFlags { .flags = X86.flags | X64.flags | Arm64.flags };

    flags: u8,

    pub fn initJson(architectures: []json.Value) ArchFlags {
        if (architectures.len == 0) {
            return ArchFlags.all;
        }
        var result = ArchFlags { .flags = 0 };
        for (architectures) |arch_node| {
            const arch = arch_name_map.get(arch_node.String) orelse std.debug.panic("unhandled arch '{s}'", .{arch_node.String});
            result.flags |= getFlag(arch).flags;
        }
        return result;
    }
};


pub fn jsonObjEnforceKnownFieldsOnly(map: std.json.ObjectMap, known_fields: []const []const u8, file_thing: anytype) !void {
    if (@TypeOf(file_thing) == *SdkFile or @TypeOf(file_thing) == *const SdkFile)
        return common.jsonObjEnforceKnownFieldsOnly(map, known_fields, file_thing.json_basename);
    if (@TypeOf(file_thing) == []const u8)
        return common.jsonObjEnforceKnownFieldsOnly(map, known_fields, file_thing);
    @compileError("unhandled file_thing type: " ++ @typeName(@TypeOf(file_thing)));
}

fn jsonObjGetRequired(map: json.ObjectMap, field: []const u8, file_thing: anytype) !json.Value {
    if (@TypeOf(file_thing) == *SdkFile or @TypeOf(file_thing) == *const SdkFile)
        return jsonObjGetRequiredImpl(map, field, file_thing.json_basename);
    if (@TypeOf(file_thing) == []const u8)
        return jsonObjGetRequiredImpl(map, field, file_thing);
    @compileError("unhandled file_thing type: " ++ @typeName(@TypeOf(file_thing)));
}
fn jsonObjGetRequiredImpl(map: json.ObjectMap, field: []const u8, file_for_error: []const u8) !json.Value {
    return map.get(field) orelse {
        // TODO: print file location?
        std.debug.warn("{s}: json object is missing '{s}' field: {}\n", .{file_for_error, field, fmtJson(map)});
        jsonPanic();
    };
}

// TODO: this should probably be in std.json
pub fn jsonEql(a: json.Value, b: json.Value) bool {
    switch (a) {
        .Integer => |a_val| switch (b) {
            .Integer => |b_val| return a_val == b_val,
            else => return false,
        },
        .NumberString => |a_val| switch (b) {
            .NumberString => |b_val| return std.mem.eql(u8, a_val, b_val),
            else => return false,
        },
        else => @panic("not impl"),
    }
}

// TODO: would be nice to have isBuiltinId in the std lib
const builtin_ids = std.ComptimeStringMap(Nothing, .{
    .{ "type", .{} },
});
pub fn isBuiltinId(s: []const u8) bool {
    if (builtin_ids.get(s)) |_| return true;
    if (s.len >= 2 and (s[0] == 'i' or s[0] == 'u')) {
        if (blk: {
            for (s[1..]) |e| {
                if (e > '9' or e < '0') break :blk false;
            }
            break :blk true;
        }) return true;
    }
    return false;
}

// NOTE: this data could be generated automatically by doing a first pass
fn getParamNamesToAvoidMapGetFn(json_name: []const u8) *const fn(s: []const u8) ?Nothing {
    if (std.mem.eql(u8, json_name, "System.Mmc")) return &std.ComptimeStringMap(Nothing, .{
        .{ "Node", .{} },
        .{ "Frame", .{} },
        .{ "Column", .{} },
        .{ "Columns", .{} },
        .{ "ScopeNamespace", .{} },
        .{ "SnapIn", .{} },
        .{ "Extension", .{} },
        .{ "View", .{} },
        .{ "Document", .{} },
    }).get;
    if (std.mem.eql(u8, json_name, "UI.TabletPC")) return &std.ComptimeStringMap(Nothing, .{
        .{ "EventMask", .{} },
        .{ "InkDisplayMode", .{} },
    }).get;
    if (std.mem.eql(u8, json_name, "UI.Shell")) return &std.ComptimeStringMap(Nothing, .{
        .{ "Folder", .{} },
    }).get;
    if (std.mem.eql(u8, json_name, "Graphics.DirectShow")) return &std.ComptimeStringMap(Nothing, .{
        .{ "Quality", .{} },
        .{ "ScanModulationTypes", .{} },
        .{ "AnalogVideoStandard", .{} },
    }).get;
    return &EmptyComptimeStringMap(Nothing).get;
}

pub const FmtParamId = struct {
    s: []const u8,
    avoid_lookup: *const fn(s: []const u8) ?Nothing,
    pub fn format(
        self: @This(),
        comptime fmt: []const u8,
        options: std.fmt.FormatOptions,
        writer: anytype,
    ) !void {
        _ = fmt;
        _ = options;
        if (self.avoid_lookup.*(self.s)) |_| {
            try writer.print("_param_{s}", .{self.s});
        } else if (isBuiltinId(self.s)) {
            try writer.print("{s}_", .{self.s});
        } else {
            try writer.print("{}", .{std.zig.fmtId(self.s)});
        }
    }
};
pub fn fmtParamId(s: []const u8, avoid_lookup: *const fn(s: []const u8) ?Nothing) FmtParamId {
    return FmtParamId { .s = s, .avoid_lookup = avoid_lookup };
}

fn cleanDir(dir: std.fs.Dir, sub_path: []const u8) !void {
    try dir.deleteTree(sub_path);
    const MAX_ATTEMPTS = 30;
    var attempt : u32 = 1;
    while (true) : (attempt += 1) {
        if (attempt > MAX_ATTEMPTS) {
            std.debug.warn("Error: failed to delete '{s}' after {} attempts\n", .{sub_path, MAX_ATTEMPTS});
            return error.AlreadyReported;
        }
        // ERROR: windows.OpenFile is not handling error.Unexpected NTSTATUS=0xc0000056
        dir.makeDir(sub_path) catch |e| switch (e) {
            else => {
                std.debug.warn("[DEBUG] makedir failed with {}\n", .{e});
                //return error.AlreadyReported;
                continue;
            },
        };
        break;
    }

}

fn withoutCrLen(s: []const u8) usize {
    @setEvalBranchQuota(3000);
    return s.len - std.mem.count(u8, s, "\r");
}

fn removeCr(comptime s: []const u8) *const [withoutCrLen(s):0]u8 {
    comptime {
        const len = withoutCrLen(s);
        var without_cr: [len:0]u8 = undefined;
        var i: usize = 0;
        for (s) |e| {
            if (e != '\r') {
                without_cr[i] = e;
                i += 1;
            }
        }
        std.debug.assert(i == len);
        return &without_cr;
    }
}