@brew-lang/sdk 0.0.0-stage → 0.3.0-alpha

package/build/fetch.js

@@ -0,0 +1,1221 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BASE_IMPORT = exports.BASE_TYPE = void 0;
+exports.tsType = tsType;
+exports.stripTypeParams = stripTypeParams;
+exports.splitParams = splitParams;
+exports.refNames = refNames;
+exports.refQuals = refQuals;
+exports.createMemberCollector = createMemberCollector;
+exports.addMethodMember = addMethodMember;
+exports.addFieldMember = addFieldMember;
+exports.assembleInterface = assembleInterface;
+exports.apiDocsToInterface = apiDocsToInterface;
+exports.extractClassLinks = extractClassLinks;
+exports.extractPackageLinks = extractPackageLinks;
+exports.isNestedHref = isNestedHref;
+exports.indexLinks = indexLinks;
+exports.makeResolver = makeResolver;
+exports.mirrorDirs = mirrorDirs;
+exports.writeMirrorIndexes = writeMirrorIndexes;
+exports.writeMirrorPackage = writeMirrorPackage;
+exports.writeBrewJson = writeBrewJson;
+exports.loadBrewMap = loadBrewMap;
+exports.resolveExternalRef = resolveExternalRef;
+exports.buildClassIndex = buildClassIndex;
+exports.importPathFor = importPathFor;
+exports.importBlockFor = importBlockFor;
+exports.withImports = withImports;
+exports.fileExportLine = fileExportLine;
+exports.buildIndex = buildIndex;
+exports.declaredNames = declaredNames;
+exports.replaceImports = replaceImports;
+exports.brewPackageName = brewPackageName;
+exports.parseBrewPackageName = parseBrewPackageName;
+exports.discoverJavadocRoots = discoverJavadocRoots;
+exports.fetchAllApiDocs = fetchAllApiDocs;
+exports.fetchApiDocs = fetchApiDocs;
+exports.writeFetched = writeFetched;
+/**
+ * brewc fetch — turn a Spigot/Bukkit javadoc page into a TypeScript interface.
+ *
+ * Fetches the page, extracts the class's public instance fields and methods
+ * from the javadoc member signatures, and generates an interface extending
+ * `JavaObject` (so the transpiler's type dispatcher treats values of the
+ * type with skript-Reflect syntax). Methods following the JavaBean
+ * convention become TS accessors:
+ *
+ *   Location getLocation()          ->  get location(): Location;
+ *   void setLocation(Location loc)  ->  set location(loc: Location);
+ */
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const JAVA_TO_TS = {
+    void: "void",
+    int: "number", long: "number", short: "number", byte: "number",
+    float: "number", double: "number", boolean: "boolean", char: "string",
+    Integer: "number", Long: "number", Short: "number", Byte: "number",
+    Float: "number", Double: "number", Boolean: "boolean", Character: "string",
+    String: "string", CharSequence: "string", Object: "object",
+};
+/**
+ * Classes outside a Bukkit-style mirrored tree (JDK, Guava, Gson,
+ * bungeecord-chat, snakeyaml, JOML) can only map to a plain TS type. When
+ * the mirrored tree itself declares such a class (fetch-javadoc of the JDK),
+ * `isTreeClass` lets it bind to its interface instead.
+ */
+const EXTERNAL_TYPES = {
+    Class: "object", Number: "number", Iterator: "object", UUID: "string",
+    File: "object", URL: "string", URI: "string", InetAddress: "object",
+    SocketAddress: "object", Logger: "object", LogRecord: "object",
+    Random: "object", Thread: "object", Runnable: "object", Future: "object",
+    Callable: "object", Stream: "object", Predicate: "object",
+    Supplier: "object", Multimap: "object", HashMap: "object",
+    ListIterator: "object", TimeZone: "object", JsonElement: "object",
+    BaseComponent: "object", Image: "object", Throwable: "object",
+    Node: "object", MappingNode: "object", Optional: "object",
+    InetSocketAddress: "object", CompletableFuture: "object",
+    InputStream: "object", OutputStream: "object", Writer: "object",
+    Reader: "object", Matrix4f: "object", Vector3f: "object",
+    Quaternionf: "object", TCommand: "any", // javadoc type variable
+    Vector2d: "object", Vector2dc: "object", Vector2f: "object", Vector2fc: "object",
+    Vector2i: "object", Vector2ic: "object", Vector3d: "object", Vector3dc: "object",
+    Vector3fc: "object", Vector3i: "object", Vector3ic: "object", // JOML
+    // java.time / java.util.concurrent / java.awt and friends
+    Instant: "object", Duration: "object", Period: "object", LocalDate: "object",
+    LocalTime: "object", LocalDateTime: "object", ZonedDateTime: "object",
+    OffsetDateTime: "object", OffsetTime: "object", ZoneId: "object",
+    ZoneOffset: "object", DayOfWeek: "object", Month: "object", Year: "object",
+    YearMonth: "object", MonthDay: "object", Clock: "object", TimeUnit: "object",
+    ChronoUnit: "object", DateTimeFormatter: "object", Color: "object",
+    BufferedImage: "object", Graphics2D: "object", RenderingHints: "object",
+    // java.util / java.util.function extras
+    Scanner: "object", BitSet: "object", StringTokenizer: "object",
+    Consumer: "object", BiConsumer: "object", Function: "object",
+    BiFunction: "object", UnaryOperator: "object", BinaryOperator: "object",
+    IntFunction: "object", ToIntFunction: "object", BooleanSupplier: "object",
+    IntConsumer: "object", DoubleConsumer: "object", LongConsumer: "object",
+    ObjIntConsumer: "object", Properties: "object", StringJoiner: "string",
+    StringBuilder: "string", Formatter: "object", Currency: "object",
+    Locale: "object", Date: "object", Calendar: "object", Timer: "object",
+    TimerTask: "object", // java.util
+    // java.net / java.nio extras
+    Socket: "object", ServerSocket: "object", HttpURLConnection: "object",
+    Path: "object", Files: "object", Charset: "object", ByteBuffer: "object",
+    CharBuffer: "object", Buffer: "object",
+    // common library types (NOT API classes like org.bukkit.Plugin — those
+    // must stay linkable to their mirrored pack via brew.json)
+    JsonObject: "object", JsonArray: "object", Gson: "object",
+    // API classes the javadoc does not document (page 404s), so no mirror can
+    // declare them: map to object instead of emitting an unresolvable name
+    ChatMessageType: "object", Dialog: "object",
+};
+/** Best-effort Java type -> TypeScript type. */
+function tsType(raw, isTreeClass) {
+    let t = raw.trim();
+    if (t.endsWith("..."))
+        t = t.slice(0, -3) + "[]"; // varargs are arrays
+    t = t.replace(/\?\s*(?:extends|super)\s+/g, ""); // wildcard bounds
+    if (t === "?")
+        return "any";
+    // strip package prefixes (java.util.List<X> -> List<X>, common in Java
+    // sources); anchored so capitalized segments (Villager.Profession,
+    // MarkerOptions.Builder) stay — they are nested-class references
+    t = t.replace(/^(?:[a-z_$][\w$]*\.)+/, "");
+    const list = /^(?:List|Set|Collection|Queue|Iterable|Iterator)<(.+)>$/.exec(t);
+    if (list)
+        return `${tsType(list[1], isTreeClass)}[]`;
+    if (/^Map<.+>$/.test(t))
+        return "object";
+    if (t.endsWith("[]"))
+        return `${tsType(t.slice(0, -2), isTreeClass)}[]`;
+    const core = t.split("<")[0].split(".").pop() ?? t;
+    if (/^[A-Z][A-Z0-9_]*$/.test(core))
+        return "any"; // type variable (T, E, T_CONS, ...)
+    // String, the boxed types, Object, ... are Skript natives: always plain TS
+    if (JAVA_TO_TS[core] !== undefined)
+        return JAVA_TO_TS[core];
+    if (isTreeClass?.(core))
+        return core; // declared/linkable by the mirror
+    const ext = EXTERNAL_TYPES[core];
+    if (ext !== undefined)
+        return ext;
+    // mirror mode (isTreeClass given): an unknown, unlinked class gets no
+    // import, so map it to object instead of emitting an unresolvable name;
+    // single-page fetch (no isTreeClass) keeps the bare name as a plain ref
+    return isTreeClass ? "object" : (core || "any");
+}
+/** Strip tags/entities/annotations from a javadoc signature block. */
+function cleanSignature(html) {
+    return html
+        .replace(/\u200B/g, "") // javadoc zero-width spaces after identifiers
+        // javadoc PREVIEW marks (<sup class="preview-mark">PREVIEW</sup>) must
+        // go before the tags, or their text glues onto the type name
+        .replace(/<sup class="preview-mark">[\s\S]*?<\/sup>/g, " ")
+        .replace(/<[^>]+>/g, "")
+        .replace(/&nbsp;/g, " ")
+        .replace(/&lt;/g, "<")
+        .replace(/&gt;/g, ">")
+        .replace(/&amp;/g, "&")
+        .replace(/&quot;/g, '"')
+        .replace(/@\w+\s*\([^)]*\)/g, "") // annotations with arguments
+        .replace(/@\w+/g, "") // bare annotations
+        .replace(/\s+/g, " ")
+        .trim();
+}
+/** Lowercase the first character: getLocation -> location. */
+function propertyName(getterSuffix) {
+    if (!getterSuffix)
+        return "";
+    return getterSuffix[0].toLowerCase() + getterSuffix.slice(1);
+}
+/**
+ * Strip a leading method type-parameter clause (`<T extends Comparable<T>>`)
+ * from a signature header, at any nesting depth. The clause must directly
+ * follow whitespace-separated modifier words, so a generic RETURN type
+ * (`List<Gadget> foo()`) is kept: "List<" has no space before "<".
+ */
+function stripTypeParams(header) {
+    const m = /^((?:\w+\s+)*?)</.exec(header);
+    if (!m)
+        return header;
+    const open = m[1].length; // index of '<'
+    let depth = 0;
+    for (let i = open; i < header.length; i++) {
+        if (header[i] === "<")
+            depth++;
+        else if (header[i] === ">" && --depth === 0)
+            return m[1] + header.slice(i + 1);
+    }
+    return header;
+}
+/** Parameter names that collide with TypeScript keywords (Java allows them). */
+const TS_RESERVED = new Set([
+    "function", "class", "interface", "enum", "constructor", "get", "set",
+    "static", "public", "private", "protected", "readonly", "declare",
+    "module", "namespace", "type", "new", "delete", "in", "of", "var", "let",
+    "const", "return", "if", "else", "for", "while", "do", "switch", "case",
+    "break", "continue", "default", "extends", "implements", "import",
+    "export", "await", "yield", "async", "arguments",
+]);
+/** Split a Java parameter list on top-level commas. */
+function splitParams(params, isTreeClass) {
+    const raw = [];
+    let depth = 0;
+    let current = "";
+    for (const ch of params) {
+        if (ch === "<")
+            depth++;
+        if (ch === ">")
+            depth--;
+        if (ch === "," && depth === 0) {
+            raw.push(current);
+            current = "";
+        }
+        else {
+            current += ch;
+        }
+    }
+    if (current.trim())
+        raw.push(current);
+    return raw.map((p) => {
+        // drop parameter modifiers ("final World w" -> type "World", name "w")
+        const parts = p.trim().split(/\s+/).filter((w) => w !== "final");
+        let name = parts[parts.length - 1];
+        if (TS_RESERVED.has(name))
+            name += "_"; // e.g. a Consumer parameter named "function"
+        const type = parts.slice(0, -1).join(" ");
+        return { name, type: tsType(type, isTreeClass), raw: type };
+    });
+}
+/** Class-like names referenced by a Java type expression ("List<org.bukkit.entity.Entity>" -> ["Entity"]). */
+function refNames(rawType, isTreeClass) {
+    return [...refQuals(rawType, isTreeClass).keys()];
+}
+/**
+ * Like refNames, but also keeps the package-qualified form of each ref
+ * ("org.bukkit.World"), so a reference to a class the mirrored tree does
+ * not declare can be linked to the brew package providing it (see
+ * resolveExternalRef). Map: ref ("World", "Villager.Profession") ->
+ * qualified name ("org.bukkit.World", "Villager.Profession").
+ */
+function refQuals(rawType, isTreeClass) {
+    // JDK collections are structural, not cross-references to the API's classes
+    const CONTAINERS = new Set(["List", "Set", "Map", "Collection", "Iterable", "Queue", "Iterator"]);
+    const quals = new Map();
+    for (const m of rawType.matchAll(/[A-Za-z_$][\w$]*(?:\.[A-Za-z_$][\w$]*)*/g)) {
+        const full = m[0];
+        // strip package segments (lowercase): org.bukkit.World -> World,
+        // Villager.Profession -> Villager.Profession (a nested class reference)
+        const segments = full.split(".");
+        while (segments.length > 1 && /^[a-z_$]/.test(segments[0]))
+            segments.shift();
+        const ref = segments.join(".");
+        const core = segments[segments.length - 1];
+        if (!/^[A-Z]/.test(core))
+            continue; // primitives and type parameters
+        if (CONTAINERS.has(core))
+            continue;
+        if (JAVA_TO_TS[core] !== undefined || core === "void")
+            continue;
+        // external classes are references only when the tree declares them
+        if (EXTERNAL_TYPES[core] !== undefined && !isTreeClass?.(ref))
+            continue;
+        if (!quals.has(ref))
+            quals.set(ref, full);
+    }
+    return quals;
+}
+/**
+ * Collects interface members, resolving accessor/method name clashes the
+ * same way for javadoc pages and Java sources (shared by both parsers).
+ *
+ * TS allows method overloads and getter/setter pairs, but not two
+ * accessors of the same kind (setTypes(Tag) / setTypes(Collection)), nor
+ * a method or field sharing a property's name (header()/getHeader()).
+ */
+function createMemberCollector() {
+    const members = [];
+    const seen = new Map(); // accessor overload detection
+    const memberKinds = new Map(); // name -> get/set/method/field
+    const addMember = (member) => {
+        if (members.includes(member))
+            return; // exact duplicate signature
+        const bare = member.replace(/^static\s+/, ""); // parse without the static prefix
+        const prop = bare.match(/^(?:get|set) ([A-Za-z_$][\w$]*)/)?.[1];
+        const kind = prop ? bare.slice(0, 3).trim() : bare.includes("(") ? "method" : "field";
+        const memberName = prop ?? bare.match(/^([A-Za-z_$][\w$]*)/)?.[1] ?? "";
+        const kinds = memberKinds.get(memberName) ?? new Set();
+        const isAccessor = kind === "get" || kind === "set";
+        // methods overload freely; clashes are accessors vs methods/fields
+        // (a method may not share a property's name) and field vs anything
+        const clash = kinds.size > 0 && (isAccessor
+            ? [...kinds].some((k) => k !== "get" && k !== "set")
+            : [...kinds].some((k) => k !== "method"));
+        if (clash)
+            return;
+        const key = isAccessor ? `${kind} ${memberName}` : member;
+        const dup = seen.get(key) ?? 0;
+        seen.set(key, dup + 1);
+        kinds.add(kind);
+        memberKinds.set(memberName, kinds);
+        members.push(dup === 0 ? member : member.replace(/^(\s*(?:static\s+)?(?:get|set )?)([A-Za-z_]\w*)/, (_s, pre, n2) => `${pre}${n2}_${dup + 1}`));
+    };
+    return { members, addMember };
+}
+/** Turn a parsed Java method signature into an interface member (shared by
+ * the javadoc and Java-source parsers). */
+function addMethodMember(sig, ctx) {
+    let mName = sig.name;
+    // javadoc often omits the public modifier entirely; only members
+    // explicitly marked otherwise are skipped
+    if (/\b(private|protected)\b/.test(sig.mods))
+        return;
+    if (!ctx.includeStatic && /\bstatic\b/.test(sig.mods))
+        return;
+    if (mName === ctx.className)
+        return; // constructor
+    const plist = splitParams(sig.params, ctx.isTreeClass);
+    const retT = tsType(sig.ret, ctx.isTreeClass);
+    ctx.addRefs(sig.ret);
+    for (const p of plist)
+        ctx.addRefs(p.raw);
+    const isGetter = /^get[A-Z]/.test(mName) && plist.length === 0 && retT !== "void";
+    const isSetter = /^set[A-Z]/.test(mName) && plist.length === 1 && retT === "void";
+    let member;
+    // java.lang.Object's public instance methods: a subclass override
+    // with a different parameter count cannot legally extend the base
+    // interface (Certificate.toString(boolean) vs toString()), so those
+    // rare incompatible overloads get a distinguishing suffix
+    const BASE_PARAMS = {
+        hashCode: [0], toString: [0], equals: [1], notify: [0], notifyAll: [0],
+    };
+    if (Object.hasOwn(BASE_PARAMS, mName) && !BASE_PARAMS[mName].includes(plist.length)) {
+        mName = `${mName}_2`;
+    }
+    if (isGetter && propertyName(mName.slice(3))) {
+        member = `get ${propertyName(mName.slice(3))}(): ${retT};`;
+    }
+    else if (isSetter && propertyName(mName.slice(3))) {
+        member = `set ${propertyName(mName.slice(3))}(${plist[0].name}: ${plist[0].type});`;
+    }
+    else {
+        const args = plist.map((p) => `${p.name}: ${p.type}`).join(", ");
+        member = `${mName}(${args}): ${retT};`;
+    }
+    // declare-class members carry their static modifier, so the class's
+    // static side resolves in editors (BukkitAdapter.worldIdentifier)
+    if (ctx.includeStatic && /\bstatic\b/.test(sig.mods))
+        member = `static ${member}`;
+    ctx.addMember(member);
+}
+/** Turn a parsed Java field signature into an interface member (shared by
+ * the javadoc and Java-source parsers). */
+function addFieldMember(sig, ctx) {
+    if (/\b(private|protected)\b/.test(sig.mods))
+        return;
+    if (!ctx.includeStatic && /\bstatic\b/.test(sig.mods))
+        return;
+    ctx.addRefs(sig.type);
+    const field = `${sig.name}: ${tsType(sig.type, ctx.isTreeClass)};`;
+    ctx.addMember(ctx.includeStatic && /\bstatic\b/.test(sig.mods) ? `static ${field}` : field);
+}
+/** Assemble the generated declaration from collected members (shared by the
+ * javadoc and Java-source generators). Mirrors emit `export declare class` —
+ * not `interface` — because only classes carry a static side, so static
+ * members (emitted with the `static` modifier) resolve as `Class.member` in
+ * editors and `declare class` is a drop-in for the interface shape. */
+function assembleInterface(opts) {
+    const body = opts.members.length
+        ? opts.members.map((x) => `  ${x}`).join("\n")
+        : "  // no public members found";
+    // the full Java class location for the transpiler's import section
+    const docBlock = opts.pkg ? `/**\n * @classloc ${opts.pkg}.${opts.fullName}\n */\n` : "";
+    // java.lang.Object itself is the root: it cannot extend or import itself
+    const isBase = opts.name === exports.BASE_TYPE.name;
+    const ts = `${opts.sourceLine}\n` +
+        `// Extends ${exports.BASE_TYPE.name} (java.lang.Object) from ${exports.BASE_TYPE.module}.\n` +
+        "\n" +
+        docBlock +
+        `export declare class ${opts.name}${isBase ? "" : ` extends ${exports.BASE_TYPE.name}`} {\n${body}\n}\n`;
+    return { name: opts.name, ts, refs: [...opts.refs].filter((r) => r !== opts.name) };
+}
+/**
+ * Generate the interface source from javadoc HTML (pure, testable).
+ * Targets the modern javadoc layout (`<div class="member-signature">`).
+ *
+ * `refs` lists the class-like names the members reference — candidates for
+ * imports; the fetch-javadoc mirror turns them into `import type` statements
+ * so the tree cross-references itself. `opts.name` / `opts.fullName` override
+ * the derived class name (nested classes declare as their last name segment,
+ * but keep the dotted name for @classloc).
+ */
+function apiDocsToInterface(html, url, opts = {}) {
+    // Class name: the javadoc header ("Class Location" -> Location), else the
+    // page title, else the URL basename (Location.html -> Location). Dotted
+    // header names belong to nested classes (Enum Class AbstractArrow.PickupStatus)
+    // and javadoc's PREVIEW types (StructuredTaskScope.SubtaskPREVIEW): the
+    // interface keeps the last segment, @classloc keeps the dots.
+    const h1 = /<h1[^>]*>\s*(?:(?:Class|Interface|Enum(?:\s+Class)?|Record|Annotation(?:\s+Interface)?)\s+)?([A-Za-z_]\w*(?:\.[A-Za-z_]\w*)*)/.exec(html)?.[1] ?? "";
+    const title = /<title>\s*(?:(?:Class|Interface|Enum|Record)\s+)?([A-Za-z_]\w*)/.exec(html)?.[1] ?? "";
+    const urlName = decodeURIComponent((url.split("/").pop() ?? "").replace(/\.html.*$/, ""));
+    const keyword = /^(Class|Interface|Enum|Record|Annotation)$/;
+    const name = opts.name ||
+        (h1 && !keyword.test(h1) ? h1.split(".").pop() : "") ||
+        (title && !keyword.test(title) ? title : "") ||
+        urlName.split(".").pop() || "FetchedApi";
+    const fullName = opts.fullName ||
+        (h1 && !keyword.test(h1) && h1.includes(".") ? h1 : "") ||
+        urlName || name;
+    const collector = createMemberCollector();
+    const refs = new Set();
+    const ctx = {
+        className: name,
+        isTreeClass: opts.isTreeClass,
+        addRefs: (rawType) => {
+            for (const ref of refNames(rawType, opts.isTreeClass))
+                refs.add(ref);
+        },
+        addMember: collector.addMember,
+    };
+    const sigRe = /<div class="member-signature">([\s\S]*?)<\/div>/g;
+    let m;
+    while ((m = sigRe.exec(html))) {
+        // strip the generic type-parameter marker ([modifiers] <T extends X> Ret name(...))
+        // and the throws clause (…() throws IOException) — the method regex
+        // anchors on the closing paren
+        const sig = stripTypeParams(cleanSignature(m[1])).replace(/\s*throws\s+[\w\s.,$]+$/, "");
+        // Method: [modifiers] ReturnType name(params)
+        const method = /^((?:public|protected|private|static|final|abstract|synchronized|native|default|strictfp|\s)*)\s*([^()\s][^()]*?)\s+([A-Za-z_]\w*)\s*\(([^)]*)\)\s*$/.exec(sig);
+        if (method) {
+            addMethodMember({ mods: method[1], ret: method[2], name: method[3], params: method[4] }, ctx);
+            continue;
+        }
+        // Field: [modifiers] Type name
+        const field = /^((?:public|protected|private|static|final|transient|volatile|\s)*)\s*([^()\s][^()]*?)\s+([A-Za-z_]\w*)$/.exec(sig);
+        if (field) {
+            addFieldMember({ mods: field[1], type: field[2], name: field[3] }, ctx);
+        }
+    }
+    const pkg = /package-summary\.html[^>]*>([A-Za-z0-9_.]+)</.exec(html)?.[1] ?? "";
+    return assembleInterface({
+        name,
+        fullName,
+        pkg,
+        sourceLine: `// Generated by brewc fetch from ${url}`,
+        members: collector.members,
+        refs,
+    });
+}
+/** Extract class page paths from an allclasses-index/allclasses page (pure). */
+function extractClassLinks(html, opts = {}) {
+    const links = new Set();
+    const re = /<a[^>]+href="([^"]+\.html)"/g;
+    let m;
+    while ((m = re.exec(html))) {
+        let href = m[1].replace(/^\.\//, "").split("#")[0];
+        if (/^[a-z][\w+.-]*:/i.test(href) || href.startsWith("/") || href.startsWith("//"))
+            continue; // off-site link
+        // package-summary pages link their classes as bare files: resolve them
+        // against the package directory (String.html -> java/lang/String.html)
+        if (opts.resolveFrom)
+            href = path.posix.join(opts.resolveFrom, href);
+        if (href.startsWith("../"))
+            continue; // escaped the root (another module)
+        // module-qualified hrefs (java.base/java/lang/String.html) drop the
+        // module segment: a package belongs to exactly one module, so the
+        // remaining tree paths stay unique
+        if (/^[^/]*\.[^/]*\//.test(href))
+            href = href.slice(href.indexOf("/") + 1);
+        const parts = href.split("/");
+        if (parts.length < 2)
+            continue; // not inside a package
+        if (parts.slice(0, -1).some((seg) => !/^[A-Za-z_$][\w$]*$/.test(seg)))
+            continue; // not a package path
+        const file = parts[parts.length - 1];
+        const first = parts[0];
+        // nested classes (AbstractArrow.PickupStatus.html) would collide with
+        // their outer class file, so they are excluded unless requested
+        if (!opts.includeNested && /\./.test(file.replace(/\.html$/, "")))
+            continue;
+        if (file.startsWith("package-") || file.startsWith("module-") ||
+            file.startsWith("index-") || file.startsWith("allclasses"))
+            continue;
+        if (first.startsWith("index-files") || first.startsWith("jquery") ||
+            first.startsWith("script") || first.startsWith("search"))
+            continue;
+        if (parts.some((seg) => seg === "doc-files"))
+            continue; // package doc resources
+        links.add(href);
+    }
+    return [...links];
+}
+/**
+ * Packages listed on a module-summary page (pure), e.g. the Oracle javadocs
+ * (docs.oracle.com/.../api/java.base) whose modules have no allclasses page:
+ * java/io/package-summary.html, java/lang/package-summary.html, ...
+ */
+function extractPackageLinks(html) {
+    const pkgs = new Set();
+    const re = /<a[^>]+href="([^"]*package-summary\.html)"/g;
+    let m;
+    while ((m = re.exec(html))) {
+        let href = m[1].replace(/^\.\//, "").split("#")[0];
+        if (/^[a-z][\w+.-]*:/i.test(href) || href.startsWith("/") || href.startsWith("//"))
+            continue;
+        href = path.posix.join(href);
+        if (href.startsWith("../") || path.posix.dirname(href) === ".")
+            continue; // not inside a package
+        const pkgParts = href.split("/").slice(0, -1);
+        if (pkgParts.some((seg) => !/^[A-Za-z_$][\w$]*$/.test(seg)))
+            continue; // module or doc path
+        pkgs.add(href);
+    }
+    return [...pkgs].sort();
+}
+/** True when an href is a nested class page (Outer.Inner.html / .java). */
+function isNestedHref(href) {
+    return /\./.test(path.posix.basename(href).replace(/\.[^.]*$/, ""));
+}
+/**
+ * Index every class link (nested included) and pick the pages to mirror as
+ * files. `limit` caps the mirror and prunes the index so imports never
+ * point at pages that were not written.
+ */
+function indexLinks(allLinks, limit) {
+    const { classIndex, nestedIndex, nestedOwners, nested } = buildClassIndex(allLinks);
+    const links = limit ? allLinks.filter((l) => !isNestedHref(l)).slice(0, limit) : allLinks.filter((l) => !isNestedHref(l));
+    // with a limit only part of the tree is mirrored: importing classes whose
+    // pages were not written would leave the tree with unresolved modules
+    if (limit) {
+        const written = new Set(links);
+        for (const [cls, hrefs] of classIndex) {
+            if (!hrefs.some((h) => written.has(h)))
+                classIndex.delete(cls);
+        }
+        for (const [fullName, outer] of nestedIndex) {
+            if (!written.has(outer))
+                nestedIndex.delete(fullName);
+        }
+        for (const [cls, hrefs] of nestedOwners) {
+            const kept = hrefs.filter((h) => written.has(h));
+            if (kept.length)
+                nestedOwners.set(cls, kept);
+            else
+                nestedOwners.delete(cls);
+        }
+    }
+    return { links, classIndex, nestedIndex, nestedOwners, nested };
+}
+/**
+ * Bind a reference to the mirrored page declaring it (shared by the javadoc
+ * and git mirrors): top-level names resolve to their declaring page, dotted
+ * refs (Villager.Profession) to their outer class's page, and a name claimed
+ * by several classes binds the one whose package is nearest to this file's.
+ */
+function makeResolver(index, href, localNames) {
+    return (ref) => {
+        if (localNames.has(ref.split(".").pop()))
+            return null;
+        let target = null;
+        if (ref.includes(".")) {
+            // nested class reference (Villager.Profession)
+            target = index.nestedIndex.get(ref) ?? null;
+        }
+        else {
+            // top-level names win; a bare nested name (ConditionObject,
+            // package-private in a sibling class) binds the nested interface
+            // exported by its outer class's file
+            const owners = index.classIndex.get(ref) ?? index.nestedOwners.get(ref) ?? [];
+            // a name claimed by several classes (org.bukkit.block.Jukebox vs
+            // org.bukkit.block.data.type.Jukebox) binds the one whose package
+            // is nearest to this file's
+            const fromDir = path.posix.dirname(href).split("/");
+            const dist = (o) => {
+                const toDir = path.posix.dirname(o).split("/");
+                let i = 0;
+                while (i < fromDir.length && i < toDir.length && fromDir[i] === toDir[i])
+                    i++;
+                return (fromDir.length - i) + (toDir.length - i); // hops up + down
+            };
+            target = owners.length === 1 ? owners[0]
+                : [...owners].sort((a, b) => dist(a) - dist(b) || a.localeCompare(b))[0] ?? null;
+        }
+        if (!target || target === href)
+            return null; // unknown or this file
+        return importPathFor(path.posix.dirname(href), target);
+    };
+}
+/** Every directory of a mirror that needs an index.ts (mirrorDirs of the
+ * javadoc roots and the git clone alike). */
+function mirrorDirs(outRoot, targets) {
+    const dirs = new Set([outRoot]);
+    for (const { rootDir, href } of targets) {
+        const treeRoot = rootDir ? path.join(outRoot, rootDir) : outRoot;
+        dirs.add(treeRoot);
+        let d = path.join(treeRoot, path.dirname(href));
+        while (true) {
+            dirs.add(d);
+            if (d === treeRoot)
+                break;
+            d = path.dirname(d);
+        }
+    }
+    return dirs;
+}
+/**
+ * Write an index (.ts, or .d.ts for a types-only package) for every
+ * directory of a mirror: class files re-export directly, subpackages as
+ * namespaces — except at a tree root with a single top package, which
+ * re-exports it flat so `import * as org from "..."` works.
+ */
+function writeMirrorIndexes(dirs, treeRoots, ext) {
+    for (const d of dirs) {
+        const entries = fs.readdirSync(d, { withFileTypes: true });
+        const files = entries
+            .filter((e) => e.isFile() && e.name.endsWith(`.${ext}`) && e.name !== `index.${ext}`)
+            .map((e) => e.name.slice(0, -(ext.length + 1)))
+            .sort();
+        const subdirs = entries.filter((e) => e.isDirectory()).map((e) => e.name).sort();
+        // star-exporting every class file would clash on same-named nested
+        // classes, so names are claimed file by file
+        const claimed = new Set();
+        const fileExports = files.flatMap((f) => {
+            const src = fs.readFileSync(path.join(d, `${f}.${ext}`), "utf8");
+            const names = [...src.matchAll(/^export (?:declare )?(?:interface|class|type|function) (\w+)/gm)].map((m) => m[1]);
+            const line = fileExportLine(f, names, claimed);
+            return line ? [line] : [];
+        });
+        // the API root (the outDir itself, or each tree root of a multi-root
+        // mirror) exposes its single top-level package directly, so
+        // `import * as org from ".../spigot-api"` gives org.bukkit.entity.Player;
+        // with several top packages (java.base: java + javax) it wraps them,
+        // or their same-named subpackages (java.net, javax.net) would collide
+        const flat = treeRoots.has(d) && fileExports.length === 0 && subdirs.length === 1;
+        fs.writeFileSync(path.join(d, `index.${ext}`), buildIndex(fileExports, subdirs, { flat }), "utf8");
+    }
+}
+/** Write the package.json of a types-only mirror (`--package`). */
+function writeMirrorPackage(outDir, packageName, ext) {
+    // a mirror of java.base itself provides java.lang.Object at the package
+    // root (mirrors import `{ Object } from` the base module): its "types"
+    // points at the java.lang re-export index; every other package root
+    // exposes the whole mirrored tree
+    const types = fs.existsSync(path.join(outDir, "java", "lang", `index.${ext}`))
+        ? `java/lang/index.${ext}`
+        : `index.${ext}`;
+    fs.writeFileSync(path.join(outDir, "package.json"), JSON.stringify({
+        name: packageName,
+        version: "0.0.0",
+        types,
+        private: true,
+    }, null, 2) + "\n", "utf8");
+    writeBrewJson(outDir, packageName, ext);
+}
+/**
+ * Write brew.json next to package.json: a map from every Java package this
+ * mirror covers to the npm package name, so other mirrors can link their
+ * external references into this package (see loadBrewMap/resolveExternalRef):
+ *
+ *   { "java": { "org.bukkit": "@brew-types/java__org.spigotmc__spigot-api" } }
+ *
+ * Package names follow the @brew-types/<languageFileExtension>__<groupId>__<artifactId>
+ * standard (see brewPackageName), e.g. @brew-types/java__java.base for the
+ * java.base module (java.lang) and @brew-types/java__org.spigotmc__spigot-api
+ * for org.spigotmc:spigot-api (org.bukkit).
+ */
+function writeBrewJson(outDir, packageName, ext) {
+    const java = {};
+    const walk = (dir) => {
+        let entries;
+        try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        const hasClasses = entries.some((e) => e.isFile() && e.name.endsWith(`.${ext}`) && e.name !== `index.${ext}`);
+        if (hasClasses && dir !== outDir) {
+            java[path.relative(outDir, dir).split(path.sep).join(".")] = packageName;
+        }
+        for (const e of entries) {
+            if (e.isDirectory() && !e.name.startsWith("."))
+                walk(path.join(dir, e.name));
+        }
+    };
+    walk(outDir);
+    fs.writeFileSync(path.join(outDir, "brew.json"), JSON.stringify({ java }, null, 2) + "\n", "utf8");
+}
+/**
+ * Load the union of the brew.json maps found in the given directories (each
+ * dir's own brew.json plus one level of subdirectories, so both
+ * node_modules/@brew-types and a packages/ dir work): java package prefix
+ * -> npm package name.
+ */
+function loadBrewMap(searchDirs) {
+    const map = new Map();
+    const read = (file) => {
+        try {
+            const parsed = JSON.parse(fs.readFileSync(file, "utf8"));
+            if (parsed?.java && typeof parsed.java === "object") {
+                for (const [prefix, pkg] of Object.entries(parsed.java)) {
+                    if (typeof pkg === "string" && prefix)
+                        map.set(prefix, pkg);
+                }
+            }
+        }
+        catch {
+            // not a brew package (no brew.json / unreadable) — skip
+        }
+    };
+    for (const dir of searchDirs) {
+        read(path.join(dir, "brew.json"));
+        let entries;
+        try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const e of entries) {
+            if (e.isDirectory())
+                read(path.join(dir, e.name, "brew.json"));
+        }
+    }
+    return map;
+}
+/**
+ * Resolve a reference the mirrored tree does not declare to an import path
+ * in the brew package providing it (pure): with brew map
+ * { "org.bukkit": "@brew-types/java__org.spigotmc__spigot-api" }, the
+ * qualified name "org.bukkit.World" resolves to
+ * "@brew-types/java__org.spigotmc__spigot-api/org/bukkit/World". Nested
+ * classes (Outer.Inner) import from their outer class's file. The longest
+ * matching package prefix wins.
+ */
+function resolveExternalRef(ref, quals, brewMap) {
+    const prefixes = [...brewMap.keys()].filter(Boolean).sort((a, b) => b.length - a.length);
+    if (!prefixes.length)
+        return null;
+    for (const q of quals) {
+        const segs = q.split(".");
+        // package segments start lowercase, class segments uppercase
+        let i = 0;
+        while (i < segs.length - 1 && /^[a-z_$]/.test(segs[i]))
+            i++;
+        const pkg = segs.slice(0, i).join(".");
+        const cls = segs.slice(i);
+        if (!cls.length || !/^[A-Z]/.test(cls[0]))
+            continue;
+        for (const prefix of prefixes) {
+            if (pkg === prefix || pkg.startsWith(prefix + ".")) {
+                return `${brewMap.get(prefix)}/${[...segs.slice(0, i), cls[0]].join("/")}`;
+            }
+        }
+    }
+    return null;
+}
+/**
+ * Map every class of a javadoc tree to the page that declares it (pure,
+ * testable). Nested classes live in their outer class's page; they do not
+ * claim their simple name, which would shadow same-named top-level classes
+ * (TropicalFish.Pattern vs org.bukkit.block.banner.Pattern). Names claimed
+ * by more than one page are left out (an ambiguous import would silently
+ * bind the wrong class).
+ */
+function buildClassIndex(links) {
+    const owners = new Map();
+    const claim = (cls, href) => {
+        if (!owners.has(cls))
+            owners.set(cls, new Set());
+        owners.get(cls).add(href);
+    };
+    const nested = new Map();
+    const nestedIndex = new Map();
+    const nestedOwners = new Map();
+    for (const href of links) {
+        const dir = path.posix.dirname(href);
+        // strip any extension (.html javadoc pages, .java source files alike)
+        const ext = path.posix.extname(href);
+        const base = decodeURIComponent(path.posix.basename(href).replace(/\.[^.]*$/, ""));
+        if (isNestedHref(href)) {
+            const outer = path.posix.join(dir, base.slice(0, base.indexOf(".")) + ext);
+            if (!nested.has(outer))
+                nested.set(outer, []);
+            nested.get(outer).push(href);
+            nestedIndex.set(base, outer);
+            // simple names of nested classes claim nothing (they would shadow
+            // top-level classes) but remember their pages for bare references
+            const simple = base.slice(base.lastIndexOf(".") + 1);
+            if (!nestedOwners.has(simple))
+                nestedOwners.set(simple, new Set());
+            nestedOwners.get(simple).add(outer);
+        }
+        else {
+            claim(base, href);
+        }
+    }
+    const classIndex = new Map();
+    for (const [cls, hrefs] of owners)
+        classIndex.set(cls, [...hrefs]);
+    const nestedOwnerList = new Map();
+    for (const [cls, hrefs] of nestedOwners)
+        nestedOwnerList.set(cls, [...hrefs]);
+    return { classIndex, nestedIndex, nestedOwners: nestedOwnerList, nested };
+}
+/** Module path importing toHref's class from a file living in fromDir (pure).
+ * Works for any href extension (.html javadoc pages, .java source files). */
+function importPathFor(fromDir, toHref) {
+    let rel = path.posix.relative(fromDir, path.posix.dirname(toHref)) || ".";
+    if (!rel.startsWith("."))
+        rel = "./" + rel; // keep the specifier relative
+    const base = decodeURIComponent(path.posix.basename(toHref)).replace(/\.[^.]*$/, "");
+    return `${rel}/${base}`;
+}
+/** Build the `import type` block for referenced classes (pure). */
+function importBlockFor(refs, resolveImport) {
+    const chosen = new Map();
+    // dotted refs (Villager.Profession) are more specific than plain names:
+    // when both bind the same import name, the dotted one wins
+    const sorted = [...new Set(refs)].sort((a, b) => b.split(".").length - a.split(".").length || a.localeCompare(b));
+    for (const ref of sorted) {
+        const mod = resolveImport(ref);
+        if (mod === null)
+            continue;
+        const name = ref.split(".").pop();
+        if (!chosen.has(name))
+            chosen.set(name, { name, mod });
+    }
+    return [...chosen.values()].sort((a, b) => a.name.localeCompare(b.name))
+        .map((x) => `import type { ${x.name} } from "${x.mod}";`)
+        .join("\n");
+}
+/** Insert an import block after the generated header comments (pure). */
+function withImports(ts, importBlock) {
+    if (!importBlock)
+        return ts;
+    const secondNl = ts.indexOf("\n", ts.indexOf("\n") + 1) + 1;
+    return ts.slice(0, secondNl) + importBlock + "\n\n" + ts.slice(secondNl).replace(/^\n/, "");
+}
+/** index.ts content for one directory: re-export files and subdirectories. */
+/**
+ * Re-export statement for one class file (pure), or null when every name it
+ * declares was already claimed by an earlier sibling: two nested classes of
+ * the same name in one directory (Crafter.Orientation, Jigsaw.Orientation)
+ * cannot both be star-exported from its index.ts.
+ */
+function fileExportLine(file, names, claimed) {
+    const fresh = names.filter((n) => !claimed.has(n));
+    for (const n of fresh)
+        claimed.add(n);
+    if (!fresh.length)
+        return null;
+    return fresh.length === names.length
+        ? `export * from "./${file}";`
+        : `export { ${fresh.join(", ")} } from "./${file}";`;
+}
+/**
+ * index.ts content for one directory (pure). Class files re-export directly;
+ * subpackages re-export as namespaces named after their directory, so a tree
+ * mirrors Java paths: org/bukkit/index.ts gives org.bukkit.entity.Player.
+ * `opts.flat` re-exports subdirectories directly instead — used for the API
+ * root, so `import * as org from ".../spigot-api"` binds its top packages.
+ */
+function buildIndex(fileExports, subdirs, opts = {}) {
+    const lines = [
+        ...fileExports,
+        ...subdirs.map((d) => opts.flat ? `export * from "./${d}";` : `export * as ${d} from "./${d}";`),
+    ];
+    return lines.length ? lines.join("\n") + "\n" : "";
+}
+/** Names of the interfaces a generated file declares (its class + nested). */
+function declaredNames(ts) {
+    return new Set(ts.match(/^export (?:declare )?(?:interface|class|type|function) ([A-Za-z_$][\w$]*)/gm)
+        ?.map((m) => m.replace(/^export (?:declare )?(?:interface|class|type|function) /, "")) ?? []);
+}
+/** Swap the import block of an already-generated file (pure). */
+function replaceImports(ts, importBlock) {
+    const lines = ts.split("\n");
+    let i = 2; // past the two header comment lines
+    while (i < lines.length && lines[i].startsWith("import type "))
+        i++;
+    while (i < lines.length && lines[i] === "")
+        i++;
+    return lines.slice(0, 2).join("\n") + "\n" + (importBlock ? importBlock + "\n\n" : "") + lines.slice(i).join("\n");
+}
+/**
+ * @brew-types package names are `<languageFileExtension>__<groupId>__<artifactId>`,
+ * double-underscore delimited — e.g. @brew-types/java__org.spigotmc__spigot-api —
+ * so snakecase groupIds/artifactIds of future languages stay readable and the
+ * name parses unambiguously. JDK modules put the module name in place of
+ * groupId/artifactId: @brew-types/java__java.base.
+ */
+function brewPackageName(language, ...rest) {
+    return `@brew-types/${[language, ...rest].join("__")}`;
+}
+/** Inverse of brewPackageName: split on the double-underscore delimiter.
+ * Two components => <language>__<module> (JDK module), three =>
+ * <language>__<groupId>__<artifactId> (Maven coordinates). */
+function parseBrewPackageName(name) {
+    if (!name.startsWith("@brew-types/"))
+        return null;
+    const parts = name.slice("@brew-types/".length).split("__");
+    if (parts.some((p) => !p))
+        return null;
+    if (parts.length === 2)
+        return { language: parts[0], module: parts[1] };
+    if (parts.length === 3)
+        return { language: parts[0], groupId: parts[1], artifactId: parts[2] };
+    return null;
+}
+/**
+ * The base of every generated interface: java.lang.Object, provided by the
+ * @brew-types language packs — @brew-types/java__java.base: java.lang is a
+ * package inside the java.base module. Extending it gives every mirrored
+ * class Object's methods (toString, equals, hashCode, ...).
+ */
+exports.BASE_TYPE = { name: "Object", module: brewPackageName("java", "java.base") };
+exports.BASE_IMPORT = `import type { ${exports.BASE_TYPE.name} } from "${exports.BASE_TYPE.module}";`;
+const CLASS_LIST_FILES = [
+    "allclasses-index.html", // modern javadoc
+    "allclasses.html", // single-source javadoc
+    "allclasses-noframes.html", // pre-javadoc-10 frames layout
+];
+/**
+ * Read a javadoc root's class list (nested classes included); null when not a
+ * root. Redirects count as missing: the Oracle docs redirect their absent
+ * allclasses pages to the documentation homepage, whose links would mirror
+ * garbage (a tree of interfaces named after the homepage title).
+ */
+async function readClassList(rootUrl) {
+    for (const file of CLASS_LIST_FILES) {
+        const res = await fetch(rootUrl + file);
+        if (res.ok && !res.redirected) {
+            const links = extractClassLinks(await res.text(), { includeNested: true });
+            return links.length ? links : null;
+        }
+    }
+    return null;
+}
+/**
+ * Read a module javadoc's class list by crawling its package pages; null
+ * when the URL is not a module root. Oracle's per-module javadocs (java.base)
+ * have no allclasses page: module-summary.html links every package summary,
+ * and those link their class pages.
+ */
+async function readModuleClassList(rootUrl) {
+    const res = await fetch(rootUrl + "module-summary.html");
+    if (!res.ok || res.redirected)
+        return null;
+    const pkgs = extractPackageLinks(await res.text());
+    if (!pkgs.length)
+        return null;
+    const links = new Set();
+    for (const pkg of pkgs) {
+        const page = await fetch(rootUrl + pkg);
+        if (!page.ok || page.redirected)
+            continue;
+        for (const link of extractClassLinks(await page.text(), {
+            includeNested: true,
+            resolveFrom: path.posix.dirname(pkg),
+        })) {
+            links.add(link);
+        }
+    }
+    return links.size ? [...links] : null;
+}
+/**
+ * Extract javadoc roots linked from a landing page (pure, testable).
+ * Some hubs are not a javadoc root themselves: the SpigotMC hub
+ * (hub.spigotmc.org/javadocs) links each API's javadoc as
+ * <root>/index.html?overview-summary.html (bukkit/, spigot/).
+ */
+function discoverJavadocRoots(html, base) {
+    const roots = new Set();
+    const re = /<a[^>]+href="([^"]+)"/g;
+    let m;
+    while ((m = re.exec(html))) {
+        const href = m[1].split("#")[0];
+        // javadoc entry pages: <root>/index.html[?overview-summary.html]
+        const entry = /^([^?#]*\/)?index\.html(?:\?overview-summary\.html)?$/.exec(href);
+        if (!entry)
+            continue;
+        let url;
+        try {
+            url = new URL((entry[1] ?? "") + "index.html", base);
+        }
+        catch {
+            continue;
+        }
+        const root = url.href.slice(0, -"index.html".length);
+        if (!root.startsWith(base) || root === base)
+            continue;
+        roots.add(root);
+    }
+    return [...roots].sort();
+}
+/**
+ * Walk the entire javadoc of a Bukkit/Spigot API: read the class list, fetch
+ * every class page, and mirror the package tree as .ts interfaces on disk,
+ * with an index.ts re-exporting each directory level.
+ *
+ * A base URL that is not a javadoc root itself works too when it links the
+ * javadoc roots (the SpigotMC hub); each discovered root is mirrored under
+ * its own subdirectory of outDir so same-named packages cannot collide.
+ */
+async function fetchAllApiDocs(baseUrl, outDir, opts = {}) {
+    if (typeof fetch === "undefined") {
+        throw new Error("brewc fetch requires Node.js 18 or newer (global fetch)");
+    }
+    const base = baseUrl.endsWith("/") ? baseUrl : baseUrl + "/";
+    const makeRoot = (url, dir, allLinks, limit) => {
+        const { links, classIndex, nestedIndex, nestedOwners, nested } = indexLinks(allLinks, limit);
+        return { url, dir, links, classIndex, nestedIndex, nestedOwners, nested };
+    };
+    const roots = [];
+    const rootLinks = await readClassList(base);
+    const moduleLinks = rootLinks ? null : await readModuleClassList(base);
+    if (rootLinks) {
+        roots.push(makeRoot(base, "", rootLinks, opts.limit));
+    }
+    else if (moduleLinks) {
+        if (opts.log)
+            opts.log(`no class list at ${base}; crawling the module's packages`);
+        roots.push(makeRoot(base, "", moduleLinks, opts.limit));
+    }
+    else {
+        let status = 404;
+        try {
+            const page = await fetch(base);
+            status = page.status;
+            if (page.ok) {
+                for (const rootUrl of discoverJavadocRoots(await page.text(), base)) {
+                    const links = await readClassList(rootUrl);
+                    if (links) {
+                        const name = new URL(rootUrl).pathname.replace(/\/+$/, "").split("/").pop() ?? "api";
+                        roots.push(makeRoot(rootUrl, name, links, opts.limit));
+                    }
+                }
+            }
+        }
+        catch {
+            // fall through: report the class-list error below
+        }
+        if (!roots.length) {
+            throw new Error(`cannot read the class list (${CLASS_LIST_FILES.join(" / ")}) at ${base}: ${status}`);
+        }
+        if (opts.log) {
+            const names = roots.map((r) => new URL(r.url).pathname.replace(/\/+$/, "").split("/").pop());
+            opts.log(`no javadoc at ${base}; mirroring ${[...new Set(names)].join(", ")}`);
+        }
+        if (roots.length === 1)
+            roots[0].dir = ""; // single root: mirror directly in outDir
+    }
+    const errors = [];
+    let done = 0;
+    const targets = roots.flatMap((root) => root.links.map((href) => ({ root, href })));
+    const queue = [...targets];
+    const total = targets.length;
+    /** Bind a reference to the mirrored page declaring it (shared by the
+     * generation pass and the import reconciliation below). */
+    const resolveFor = (root, href, localNames) => makeResolver(root, href, localNames);
+    const generated = [];
+    const workers = Array.from({ length: opts.concurrency ?? 8 }, async () => {
+        for (let item = queue.shift(); item; item = queue.shift()) {
+            const { root, href } = item;
+            try {
+                const page = await fetch(root.url + href);
+                if (!page.ok || page.redirected) {
+                    errors.push(`${href}: ${page.status}`);
+                }
+                else {
+                    const pageHtml = await page.text();
+                    // package-private nested classes (AbstractQueuedSynchronizer.
+                    // ConditionObject) are absent from every class list: discover them
+                    // from their outer class's own page and register them for the
+                    // import reconciliation below
+                    const ownName = decodeURIComponent(path.posix.basename(href, ".html"));
+                    const dirPosix = path.posix.dirname(href);
+                    const nestedHrefs = [...(root.nested.get(href) ?? [])];
+                    for (const found of extractClassLinks(pageHtml, { includeNested: true, resolveFrom: dirPosix })) {
+                        if (!isNestedHref(found) || nestedHrefs.includes(found))
+                            continue;
+                        const base = decodeURIComponent(path.posix.basename(found, ".html"));
+                        if (base.slice(0, base.indexOf(".")) !== ownName)
+                            continue;
+                        nestedHrefs.push(found);
+                        root.nestedIndex.set(base, href);
+                        const simple = base.slice(base.lastIndexOf(".") + 1);
+                        const owners = root.nestedOwners.get(simple) ?? [];
+                        if (!owners.includes(href))
+                            root.nestedOwners.set(simple, [...owners, href]);
+                    }
+                    // cross-references: import the mirrored declaration of every
+                    // referenced class of this javadoc tree
+                    // a class the tree declares keeps its name (JDK externals like
+                    // File or Random bind to their mirrored interfaces); unknown ones
+                    // still fall back to plain TS types
+                    const isTreeClass = (cls) => root.classIndex.has(cls) || root.nestedIndex.has(cls);
+                    // nested classes (Outer.Inner) are appended to their outer class's
+                    // file — as interfaces they cannot form files of their own — so the
+                    // import block covers the union of all their references too
+                    const outer = apiDocsToInterface(pageHtml, root.url + href, { isTreeClass });
+                    const allRefs = [...outer.refs];
+                    const parts = [outer.ts];
+                    for (const nestedHref of nestedHrefs) {
+                        try {
+                            const nestedPage = await fetch(root.url + nestedHref);
+                            if (!nestedPage.ok || nestedPage.redirected) {
+                                errors.push(`${nestedHref}: ${nestedPage.status}`);
+                                continue;
+                            }
+                            const nested = apiDocsToInterface(await nestedPage.text(), root.url + nestedHref, { isTreeClass });
+                            allRefs.push(...nested.refs);
+                            parts.push(nested.ts);
+                        }
+                        catch (e) {
+                            errors.push(`${nestedHref}: ${e.message}`);
+                        }
+                    }
+                    // files declaring the base type (java/lang/Object.ts) cannot
+                    // import it from its package: the import would shadow their export
+                    const block = [
+                        ...declaredNames(parts.join("\n")).has(exports.BASE_TYPE.name) ? [] : [exports.BASE_IMPORT],
+                        ...importBlockFor(allRefs, resolveFor(root, href, declaredNames(parts.join("\n")))) ? [importBlockFor(allRefs, resolveFor(root, href, declaredNames(parts.join("\n"))))] : [],
+                    ].join("\n");
+                    const full = withImports(parts.join("\n"), block);
+                    const dir = path.join(outDir, root.dir, path.dirname(href));
+                    fs.mkdirSync(dir, { recursive: true });
+                    // with --package the mirror is a types-only package: .d.ts files
+                    // referenced by "types": "index.d.ts"
+                    const file = `${outer.name}.${opts.packageName ? "d.ts" : "ts"}`;
+                    fs.writeFileSync(path.join(dir, file), full, "utf8");
+                    generated.push({ file: path.join(dir, file), root, href, refs: allRefs });
+                }
+            }
+            catch (e) {
+                errors.push(`${href}: ${e.message}`);
+            }
+            done++;
+            if (opts.log && (done % 25 === 0 || done === total)) {
+                opts.log(`fetched ${done}/${total} classes`);
+            }
+        }
+    });
+    await Promise.all(workers);
+    // nested classes discovered mid-run (ConditionObject, found on its outer
+    // class's page) can satisfy imports of files mirrored earlier: recompute
+    // every import block against the now-complete index
+    for (const g of generated) {
+        const src = fs.readFileSync(g.file, "utf8");
+        const local = declaredNames(src);
+        const resolved = importBlockFor(g.refs, resolveFor(g.root, g.href, local));
+        const block = (local.has(exports.BASE_TYPE.name) ? [resolved] : [exports.BASE_IMPORT, resolved])
+            .filter(Boolean).join("\n");
+        const rewritten = replaceImports(src, block);
+        if (rewritten !== src)
+            fs.writeFileSync(g.file, rewritten, "utf8");
+    }
+    // index for every directory, bottom-up so parents list their children
+    // (.ts files, or .d.ts when the mirror is a types-only package)
+    const ext = opts.packageName ? "d.ts" : "ts";
+    const outRoot = path.resolve(outDir);
+    const treeRoots = new Set([outRoot, ...roots.map((r) => path.join(outRoot, r.dir))]);
+    const dirs = mirrorDirs(outRoot, targets.map(({ root, href }) => ({ rootDir: root.dir, href })));
+    writeMirrorIndexes(dirs, treeRoots, ext);
+    if (opts.packageName)
+        writeMirrorPackage(outDir, opts.packageName, ext);
+    return { classes: total - errors.length, errors: [...new Set(errors)] };
+}
+/** Fetch a javadoc page and generate its TypeScript interface. */
+async function fetchApiDocs(url) {
+    if (typeof fetch === "undefined") {
+        throw new Error("brewc fetch requires Node.js 18 or newer (global fetch)");
+    }
+    const res = await fetch(url);
+    if (!res.ok)
+        throw new Error(`fetch failed: ${res.status} ${res.statusText}`);
+    const { name, ts } = apiDocsToInterface(await res.text(), url);
+    return { name, ts: name === exports.BASE_TYPE.name ? ts : withImports(ts, exports.BASE_IMPORT) };
+}
+/** Write a fetch result, used by the CLI. */
+function writeFetched(result, output) {
+    const file = output ?? `${result.name}.ts`;
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, result.ts, "utf8");
+    return file;
+}
+//# sourceMappingURL=fetch.js.map