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

package/build/fetch.d.ts

@@ -0,0 +1,294 @@
+/** Best-effort Java type -> TypeScript type. */
+export declare function tsType(raw: string, isTreeClass?: (name: string) => boolean): string;
+/**
+ * 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 "<".
+ */
+export declare function stripTypeParams(header: string): string;
+/** Split a Java parameter list on top-level commas. */
+export declare function splitParams(params: string, isTreeClass?: (name: string) => boolean): Array<{
+    name: string;
+    type: string;
+    raw: string;
+}>;
+/** Class-like names referenced by a Java type expression ("List<org.bukkit.entity.Entity>" -> ["Entity"]). */
+export declare function refNames(rawType: string, isTreeClass?: (name: string) => boolean): string[];
+/**
+ * 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").
+ */
+export declare function refQuals(rawType: string, isTreeClass?: (name: string) => boolean): Map<string, string>;
+/**
+ * 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()).
+ */
+export declare function createMemberCollector(): {
+    members: string[];
+    addMember: (member: string) => void;
+};
+/** Context shared by the javadoc and Java-source member parsers. */
+export interface MemberContext {
+    /** Simple name of the declaring class (its constructors are skipped). */
+    className: string;
+    isTreeClass?: (name: string) => boolean;
+    /** Include static members. The git mirror sets this — utility classes are
+     * all-static, so skipping statics would empty them; the javadoc mirror
+     * leaves it off. (TS interfaces cannot declare `static`, so they are
+     * mirrored as plain members.) */
+    includeStatic?: boolean;
+    addRefs: (rawType: string) => void;
+    addMember: (member: string) => void;
+}
+/** Turn a parsed Java method signature into an interface member (shared by
+ * the javadoc and Java-source parsers). */
+export declare function addMethodMember(sig: {
+    mods: string;
+    ret: string;
+    name: string;
+    params: string;
+}, ctx: MemberContext): void;
+/** Turn a parsed Java field signature into an interface member (shared by
+ * the javadoc and Java-source parsers). */
+export declare function addFieldMember(sig: {
+    mods: string;
+    type: string;
+    name: string;
+}, ctx: MemberContext): void;
+/** 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. */
+export declare function assembleInterface(opts: {
+    name: string;
+    fullName: string;
+    pkg: string;
+    /** First header line, e.g. `// Generated by brewc fetch from <url>`. */
+    sourceLine: string;
+    members: string[];
+    refs: Iterable<string>;
+}): {
+    name: string;
+    ts: string;
+    refs: string[];
+};
+/**
+ * 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).
+ */
+export declare function apiDocsToInterface(html: string, url: string, opts?: {
+    name?: string;
+    fullName?: string;
+    isTreeClass?: (name: string) => boolean;
+}): {
+    name: string;
+    ts: string;
+    refs: string[];
+};
+/** Extract class page paths from an allclasses-index/allclasses page (pure). */
+export declare function extractClassLinks(html: string, opts?: {
+    includeNested?: boolean;
+    resolveFrom?: string;
+}): string[];
+/**
+ * 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, ...
+ */
+export declare function extractPackageLinks(html: string): string[];
+/** True when an href is a nested class page (Outer.Inner.html / .java). */
+export declare function isNestedHref(href: string): boolean;
+/** The class indexes a mirror resolver needs (see buildClassIndex). */
+export interface ClassIndexLike {
+    classIndex: Map<string, string[]>;
+    nestedIndex: Map<string, string>;
+    nestedOwners: Map<string, string[]>;
+}
+/**
+ * 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.
+ */
+export declare function indexLinks(allLinks: string[], limit?: number): {
+    links: string[];
+    classIndex: Map<string, string[]>;
+    nestedIndex: Map<string, string>;
+    nestedOwners: Map<string, string[]>;
+    nested: Map<string, string[]>;
+};
+/**
+ * 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.
+ */
+export declare function makeResolver(index: ClassIndexLike, href: string, localNames: Set<string>): (ref: string) => string | null;
+/** Every directory of a mirror that needs an index.ts (mirrorDirs of the
+ * javadoc roots and the git clone alike). */
+export declare function mirrorDirs(outRoot: string, targets: Array<{
+    rootDir: string;
+    href: string;
+}>): Set<string>;
+/**
+ * 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.
+ */
+export declare function writeMirrorIndexes(dirs: Set<string>, treeRoots: Set<string>, ext: string): void;
+/** Write the package.json of a types-only mirror (`--package`). */
+export declare function writeMirrorPackage(outDir: string, packageName: string, ext: string): void;
+/**
+ * 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).
+ */
+export declare function writeBrewJson(outDir: string, packageName: string, ext: string): void;
+/**
+ * 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.
+ */
+export declare function loadBrewMap(searchDirs: string[]): Map<string, string>;
+/**
+ * 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.
+ */
+export declare function resolveExternalRef(ref: string, quals: Iterable<string>, brewMap: Map<string, string>): string | 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).
+ */
+export declare function buildClassIndex(links: string[]): {
+    classIndex: Map<string, string[]>;
+    nestedIndex: Map<string, string>;
+    nestedOwners: Map<string, string[]>;
+    nested: Map<string, string[]>;
+};
+/** Module path importing toHref's class from a file living in fromDir (pure).
+ * Works for any href extension (.html javadoc pages, .java source files). */
+export declare function importPathFor(fromDir: string, toHref: string): string;
+/** Build the `import type` block for referenced classes (pure). */
+export declare function importBlockFor(refs: string[], resolveImport: (ref: string) => string | null): string;
+/** Insert an import block after the generated header comments (pure). */
+export declare function withImports(ts: string, importBlock: string): string;
+/** 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.
+ */
+export declare function fileExportLine(file: string, names: string[], claimed: Set<string>): string | null;
+/**
+ * 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.
+ */
+export declare function buildIndex(fileExports: string[], subdirs: string[], opts?: {
+    flat?: boolean;
+}): string;
+export interface FetchAllResult {
+    classes: number;
+    errors: string[];
+}
+/** Names of the interfaces a generated file declares (its class + nested). */
+export declare function declaredNames(ts: string): Set<string>;
+/** Swap the import block of an already-generated file (pure). */
+export declare function replaceImports(ts: string, importBlock: string): string;
+/**
+ * @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.
+ */
+export declare function brewPackageName(language: string, ...rest: string[]): string;
+/** Inverse of brewPackageName: split on the double-underscore delimiter.
+ * Two components => <language>__<module> (JDK module), three =>
+ * <language>__<groupId>__<artifactId> (Maven coordinates). */
+export declare function parseBrewPackageName(name: string): {
+    language: string;
+    module?: string;
+    groupId?: string;
+    artifactId?: string;
+} | 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, ...).
+ */
+export declare const BASE_TYPE: {
+    name: string;
+    module: string;
+};
+export declare const BASE_IMPORT: string;
+/**
+ * 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/).
+ */
+export declare function discoverJavadocRoots(html: string, base: string): string[];
+/**
+ * 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.
+ */
+export declare function fetchAllApiDocs(baseUrl: string, outDir: string, opts?: {
+    limit?: number;
+    concurrency?: number;
+    log?: (msg: string) => void;
+    /** npm package name for the mirror: writes a package.json so it can be
+     * installed (file:...) and imported by package specifier. */
+    packageName?: string;
+}): Promise<FetchAllResult>;
+/** Fetch a javadoc page and generate its TypeScript interface. */
+export declare function fetchApiDocs(url: string): Promise<{
+    name: string;
+    ts: string;
+}>;
+/** Write a fetch result, used by the CLI. */
+export declare function writeFetched(result: {
+    name: string;
+    ts: string;
+}, output: string | null): string;