@lwc-bolts/sf2ts 0.0.5 → 1.0.0

package/dist/apex/file.js

@@ -0,0 +1,623 @@
+import { docParagraphs, jsDoc } from "../jsdoc.js";
+import { importName } from "../names.js";
+import { schemaValueType, writeDefaultExportModule } from "../module-declaration.js";
+import { TextBuilder } from "../text-builder.js";
+import { getApexDoc, inlineDoc } from "./apexdoc.js";
+import { apexLibrary } from "./library.js";
+import { CLASSES_REGISTRY, registration, SOBJECTS_REGISTRY } from "./namespace.js";
+import { PRIMITIVE_TYPES, TypeResolver } from "./resolution.js";
+/**
+ * Converts an Apex file's top-level type to declarations: its types in the Apex namespace, then, for a
+ * class, its `@salesforce/apex` modules (or, for an SObject definition, its `@salesforce/schema`
+ * modules). Returns undefined for a file that declares no type, and throws for one with syntax errors
+ * and no type to convert. A type with syntax errors is converted as far as it parses, so a class being
+ * edited keeps its other declarations. The parse tree lives in WebAssembly memory, which isn't garbage
+ * collected, so it's deleted once the declarations are built.
+ */
+export function convertApexFile(parser, apexText, options) {
+    const tree = parser.parse(apexText);
+    try {
+        // The file's type is one of the root's children; in a tree with errors it can be under an error node,
+        // so it's the first in document order, which is the outermost. Only that search reads the whole tree.
+        const { rootNode } = tree;
+        const typeNode = rootNode.hasError
+            ? rootNode.descendantsOfType(TYPE_DECLARATIONS)[0]
+            : rootNode.namedChildren.find((child) => TYPE_DECLARATIONS.includes(child.type));
+        if (typeNode === undefined) {
+            if (rootNode.hasError) {
+                throw new Error("the file has syntax errors, and no class, interface or enum declaration was found");
+            }
+            return undefined; // no type
+        }
+        return new ApexFile(typeNode, options).convert();
+    }
+    finally {
+        tree?.delete();
+    }
+}
+const TYPE_DECLARATIONS = ["class_declaration", "interface_declaration", "enum_declaration"];
+/**
+ * One Apex file's conversion, with what its declarations depend on.
+ *
+ * A class of an installed package (a cached copy of a managed class, named `dlrs__RollupController.cls`)
+ * is declared in a namespace of the package's in the Apex namespace (`Apex.dlrs.RollupController`), where
+ * the project's references through the package (`dlrs.RollupController`) find it. Only its `global`
+ * `@AuraEnabled` methods are declared, as `@salesforce/apex/dlrs.RollupController.<method>`, since other
+ * namespaces can't import the others. In it, custom objects are the package's, a name is the package's
+ * class when it has one, then a library type or an SObject, and a dotted name, or one through the
+ * package's namespace, is the package's type (see `TypeResolver`).
+ */
+class ApexFile {
+    #builder = new TextBuilder();
+    /** The file's top-level class, interface or enum. */
+    #classNode;
+    #classNameNode;
+    #isSobject;
+    #polymorphicTargets;
+    #inaccessibleProperties;
+    /**
+     * Nested classes, interfaces and enums of the class being converted, keyed by lower-cased name (Apex
+     * names are case-insensitive) to their declared spelling.
+     */
+    #nestedTypes = new Map();
+    #projectNamespace;
+    /** The installed package the class belongs to, when it isn't the project's. */
+    #packageNamespace;
+    #resolver;
+    constructor(classNode, options) {
+        const classNameNode = classNode.childForFieldName("name");
+        if (!classNameNode) {
+            throw new Error(`the ${classNode.type.replace("_declaration", "")} has no name`);
+        }
+        this.#classNode = classNode;
+        this.#classNameNode = classNameNode;
+        this.#isSobject = options.isSobject;
+        this.#polymorphicTargets = options.polymorphicTargets;
+        this.#inaccessibleProperties = options.inaccessibleProperties;
+        this.#projectNamespace = options.projectNamespace;
+        this.#packageNamespace = options.packageNamespace;
+        this.#resolver = new TypeResolver({
+            namespace: options.apexNamespace,
+            projectNamespace: options.projectNamespace,
+            packageNamespace: options.packageNamespace,
+            className: classNameNode.text,
+            isSobject: options.isSobject,
+            nestedTypes: this.#nestedTypes,
+        });
+    }
+    convert() {
+        const builder = this.#builder;
+        let methods;
+        const typesNamespace = this.#resolver.typesNamespace;
+        if (typesNamespace === null) {
+            methods = this.#processType(this.#classNode, "");
+        }
+        else {
+            builder.write(`declare namespace ${typesNamespace} {\n`);
+            methods = this.#processType(this.#classNode, "  ");
+            if (this.#packageNamespace !== undefined) {
+                // the package's classes resolve each other through its registry (see `packageLookup`), which has
+                // their nested types too, by their dotted names
+                const outer = this.#classNameNode.text;
+                builder.write(registration("  ", CLASSES_REGISTRY, [outer, ...[...this.#nestedTypes.values()].map((nested) => `${outer}.${nested}`)]));
+            }
+            builder.write("}\n");
+        }
+        if (this.#classNode.type !== "class_declaration") {
+            // an interface or an enum has no modules
+        }
+        else if (this.#isSobject) {
+            // SObject definitions only describe records; their methods (if any) aren't callable from LWC
+            this.#addSchemaModules();
+        }
+        else {
+            // Salesforce rejects overloaded @AuraEnabled methods, so only the first of a name is declared (Apex
+            // names are case-insensitive); declaring each would give the module several default exports.
+            const declared = new Set();
+            for (const mNode of methods) {
+                const nameNode = mNode.childForFieldName("name");
+                const name = nameNode?.text.toLowerCase();
+                // instance @AuraEnabled methods are Aura getters; LWC can only import static methods
+                const { auraEnabled, modifiers } = declarationModifiers(mNode);
+                if (!nameNode || name === undefined || auraEnabled === undefined || !modifiers.has("static")) {
+                    continue;
+                }
+                if (this.#packageNamespace !== undefined && !modifiers.has("global")) {
+                    // other namespaces can only import a package's global methods
+                    continue;
+                }
+                if (declared.has(name)) {
+                    continue;
+                }
+                declared.add(name);
+                this.#transformMethodDeclaration(mNode, nameNode, auraEnabled, methods);
+            }
+        }
+        this.#addLibraryDeclarations();
+        return builder.output();
+    }
+    /** Declares a class, interface or enum, returning a class's methods. */
+    #processType(node, indent) {
+        switch (node.type) {
+            case "class_declaration":
+                return this.#processClass(node, indent);
+            case "interface_declaration":
+                this.#processInterface(node, indent);
+                return [];
+            default:
+                this.#processEnum(node, indent);
+                return [];
+        }
+    }
+    /**
+     * Declares an interface as a type any object fits, with any properties: its value is an instance of
+     * whichever class implements it, so nothing is known about its properties.
+     */
+    #processInterface(node, indent) {
+        const nameNode = node.childForFieldName("name");
+        if (!nameNode) {
+            throw new Error("an interface has no name");
+        }
+        this.#builder.write(jsDoc(indent, getApexDoc(node)?.lines ?? []));
+        this.#builder.write(`${indent}interface `);
+        this.#builder.write(nameNode.text, nameNode.startIndex, nameNode.endIndex);
+        this.#builder.write(" extends Record<string, unknown> {}\n");
+    }
+    /** Declares an enum as the union of its values' names, which is how Apex serializes them. */
+    #processEnum(node, indent) {
+        const builder = this.#builder;
+        const nameNode = node.childForFieldName("name");
+        if (!nameNode) {
+            throw new Error("an enum has no name");
+        }
+        const constants = (node.childForFieldName("body")?.namedChildren ?? [])
+            .filter((child) => child.type === "enum_constant")
+            .map((constant) => constant.childForFieldName("name") ?? constant);
+        builder.write(jsDoc(indent, getApexDoc(node)?.lines ?? []));
+        builder.write(`${indent}type `);
+        builder.write(nameNode.text, nameNode.startIndex, nameNode.endIndex);
+        builder.write(" = ");
+        if (constants.length === 0) {
+            builder.write("never");
+        }
+        constants.forEach((constant, i) => {
+            builder.write(i === 0 ? "" : " | ");
+            builder.write(JSON.stringify(constant.text), constant.startIndex, constant.endIndex);
+        });
+        builder.write(";\n");
+    }
+    /**
+     * Declares the class's type (always, so other classes and methods can reference it) and its nested
+     * classes inside the Apex namespace (or globally, without one). Returns the class's methods; only
+     * top-level classes can declare the static `@AuraEnabled` methods LWC imports.
+     */
+    #processClass(classNode, indent) {
+        const builder = this.#builder;
+        const classNameNode = classNode.childForFieldName("name");
+        if (!classNameNode) {
+            throw new Error("a nested class has no name");
+        }
+        const className = classNameNode.text;
+        const classBody = classNode.childForFieldName("body");
+        const methodsToProcess = [];
+        const fieldsToProcess = [];
+        const typesToProcess = [];
+        for (const cNode of classBody?.children ?? []) {
+            switch (cNode.type) {
+                case "method_declaration":
+                    // gather methods because AuraEnabled methods create their own exports
+                    methodsToProcess.push(cNode);
+                    break;
+                case "field_declaration": {
+                    // a field LWC can't read is declared deprecated, declared plainly, or left out
+                    const unexposed = this.#inaccessibleProperties === "include" ? [] : this.#unexposedReasons(cNode);
+                    if (this.#isSobject || this.#inaccessibleProperties !== "exclude" || unexposed.length === 0) {
+                        fieldsToProcess.push({ node: cNode, unexposed });
+                    }
+                    break;
+                }
+                case "class_declaration":
+                case "interface_declaration":
+                case "enum_declaration": {
+                    typesToProcess.push(cNode);
+                    const innerNameNode = cNode.childForFieldName("name");
+                    if (innerNameNode) {
+                        // queue up nested type names so type resolution can use them
+                        this.#nestedTypes.set(innerNameNode.text.toLowerCase(), innerNameNode.text);
+                    }
+                    break;
+                }
+            }
+        }
+        // `extends` names a type, so a base resolved through the registries gets a name of its own
+        const superclass = classNode.childForFieldName("superclass")?.namedChildren[0];
+        // an interface can't extend `unknown`, so a base a package's copy doesn't have is `{}`
+        const base = superclass === undefined ? undefined : this.#getType(superclass, { base: true });
+        builder.write(jsDoc(indent, getApexDoc(classNode, this.#isSobject)?.lines ?? []));
+        builder.write(`${indent}interface `);
+        builder.write(className, classNameNode.startIndex, classNameNode.endIndex);
+        if (superclass !== undefined && base !== undefined) {
+            builder.write(" extends ");
+            builder.write(base, superclass.startIndex, superclass.endIndex);
+        }
+        if (fieldsToProcess.length > 0) {
+            builder.write(" {\n");
+            for (const { node, unexposed } of fieldsToProcess) {
+                this.#transformFieldDeclaration(node, unexposed, indent + "  ");
+            }
+            builder.write(`${indent}}\n`);
+        }
+        else {
+            builder.write(" {}\n");
+        }
+        if (typesToProcess.length > 0) {
+            // only a top-level namespace takes `declare`; nested ones must not repeat it (TS1038)
+            builder.write(`${indent}${indent === "" ? "declare " : ""}namespace `);
+            builder.write(className, classNameNode.startIndex, classNameNode.endIndex);
+            builder.write(" {\n");
+            for (const cNode of typesToProcess) {
+                this.#processType(cNode, indent + "  ");
+            }
+            builder.write(`${indent}}\n`);
+        }
+        return methodsToProcess;
+    }
+    /**
+     * Declares a static `@AuraEnabled` method's module.
+     *
+     * @param methodNameNode the method's name
+     * @param auraEnabled the method's `@AuraEnabled` annotation
+     * @param classMethods the class's methods, where a continuation's callback is found
+     */
+    #transformMethodDeclaration(methodNode, methodNameNode, auraEnabled, classMethods) {
+        const returnType = methodNode.childForFieldName("type");
+        if (!returnType) {
+            return;
+        }
+        const continuation = annotationFlag(auraEnabled, "continuation");
+        // A continuation method returns the Continuation, but LWC receives what its callback returns.
+        const callback = continuation ? getContinuationCallback(methodNode, classMethods) : undefined;
+        this.#writeMethodModule({
+            nameNode: methodNameNode,
+            returnType: this.#getType(callback?.childForFieldName("type") ?? returnType),
+            params: this.#getMethodParameters(methodNode),
+            cacheable: annotationFlag(auraEnabled, "cacheable"),
+            continuation,
+            doc: getApexDoc(methodNode),
+            signature: apexSignature(methodNode),
+        });
+    }
+    /**
+     * Why LWC can't read a field, as what it must be (`@AuraEnabled`, `public or global`, `non-static`), or
+     * nothing when it can. An SObject definition's fields are exposed without `@AuraEnabled`.
+     */
+    #unexposedReasons(node) {
+        const { auraEnabled, modifiers } = declarationModifiers(node);
+        const reasons = [];
+        if (!this.#isSobject && auraEnabled === undefined) {
+            reasons.push("@AuraEnabled");
+        }
+        if (modifiers.has("static")) {
+            reasons.push("non-static");
+        }
+        if (!modifiers.has("public") && !modifiers.has("global")) {
+            reasons.push("public or global");
+        }
+        return reasons;
+    }
+    /** Declares a field's properties; `deprecatedReasons` are why LWC can't read it (see `#unexposedReasons`). */
+    #transformFieldDeclaration(node, deprecatedReasons, indent) {
+        const builder = this.#builder;
+        const typeNode = node.childForFieldName("type");
+        if (!typeNode) {
+            throw new Error("Type node not found");
+        }
+        // `public String a, b;` declares several fields of the same type
+        const nameNodes = node.childrenForFieldName("declarator").map((declarator) => declarator.childForFieldName("name"));
+        if (nameNodes.length === 0) {
+            throw new Error("Field doesn't have a name");
+        }
+        // A field without a type, such as `global RecordId;` (which the SObject generator writes for some
+        // fields), parses as a type with a missing name. There's nothing to declare, so skip it.
+        if (nameNodes.every((nameNode) => nameNode?.text === "")) {
+            return;
+        }
+        const declaredType = this.#getType(typeNode);
+        const doc = getApexDoc(node, this.#isSobject);
+        for (const nameNode of nameNodes) {
+            if (!nameNode) {
+                throw new Error("Field doesn't have a name");
+            }
+            const targets = typeNode.text.toLowerCase() === "sobject" ? this.#polymorphicTargets.get(nameNode.text.toLowerCase()) : undefined;
+            const typeText = targets && targets.length > 0 ? this.#polymorphicType(targets, declaredType) : declaredType;
+            /**
+             * determine if AuraEnabled & public or global & not static
+             * otherwise mark as deprecated with note (dynamic based on missing access component)
+             * {property}: {this.#getType({type})}?;
+             */
+            const deprecated = deprecatedReasons.length > 0 ? `@deprecated not exposed; property must be ${deprecatedReasons.join(", ")}` : undefined;
+            if (doc !== undefined) {
+                builder.write(jsDoc(indent, [...doc.lines, deprecated === undefined ? undefined : "", deprecated]));
+            }
+            else if (deprecated !== undefined) {
+                builder.write(`${indent}/** ${deprecated} */\n`);
+            }
+            builder.write(indent);
+            builder.write(nameNode.text, nameNode.startIndex, nameNode.endIndex);
+            builder.write("?: ");
+            builder.write(typeText, typeNode.startIndex, typeNode.endIndex);
+            builder.write(";\n");
+        }
+    }
+    /**
+     * Declares the `@salesforce/schema/<Object>` and `@salesforce/schema/<Object>.<Field>` modules of an
+     * SObject definition, for the objects and fields (such as `Account.Name`) the project has no metadata for.
+     *
+     * Each module name is a pattern with a leading `*`, which in practice only matches the exact import, and
+     * TypeScript prefers an exact `declare module` over a pattern. So when the project's own object or field
+     * metadata declares the same module, that declaration wins rather than conflicting with this one.
+     *
+     * Fields LWC can import are declared: scalar fields, lookups' Id fields and compound fields (such as
+     * `BillingAddress`). Child relationships (`List<Contact> Contacts`) and the related records of lookups
+     * (`Owner`, next to `OwnerId`, or `Account__r`) aren't fields.
+     */
+    #addSchemaModules() {
+        const builder = this.#builder;
+        const classNameNode = this.#classNameNode;
+        const objectName = classNameNode.text;
+        const fields = [];
+        for (const fieldNode of this.#classNode.childForFieldName("body")?.children ?? []) {
+            if (fieldNode.type !== "field_declaration") {
+                continue;
+            }
+            const typeNode = fieldNode.childForFieldName("type");
+            if (!typeNode) {
+                continue;
+            }
+            for (const declarator of fieldNode.childrenForFieldName("declarator")) {
+                const nameNode = declarator.childForFieldName("name");
+                if (nameNode && nameNode.text !== "") {
+                    fields.push({ nameNode, typeNode, doc: getApexDoc(fieldNode, true) });
+                }
+            }
+        }
+        const names = new Set(fields.map(({ nameNode }) => nameNode.text.toLowerCase()));
+        // LWC imports the project's own objects and fields without its namespace, which the definitions have
+        const local = (name) => importName(name, this.#projectNamespace);
+        writeDefaultExportModule(builder, {
+            name: `*@salesforce/schema/${local(objectName)}`,
+            variable: objectName,
+            type: schemaValueType(objectName),
+            range: { start: classNameNode.startIndex, end: classNameNode.endIndex },
+        });
+        for (const { nameNode, typeNode, doc } of fields) {
+            const name = nameNode.text;
+            if (typeNode.type === "generic_type" || typeNode.type === "array_type") {
+                continue; // a child relationship
+            }
+            const isScalar = PRIMITIVE_TYPES[typeNode.text.toLowerCase()] !== undefined && typeNode.text.toLowerCase() !== "sobject";
+            if (!isScalar && (names.has(`${name.toLowerCase()}id`) || /__r$/i.test(name))) {
+                continue; // a lookup's related record
+            }
+            writeDefaultExportModule(builder, {
+                name: `*@salesforce/schema/${local(objectName)}.${local(name)}`,
+                variable: name,
+                type: schemaValueType(objectName, name),
+                doc: doc?.lines,
+                range: { start: nameNode.startIndex, end: nameNode.endIndex },
+            });
+        }
+    }
+    /**
+     * The type of a polymorphic relationship, such as Task's `What`: one of its targets, once every one of
+     * them is declared, and otherwise `sobject` (its declared type), so it never names an SObject that isn't.
+     * A query that doesn't use `TYPEOF` returns the fields of the `Name` object for it (`Name`, `Type`,
+     * `Email`, ...), whichever the target is, so when the `Name` object is declared the union is intersected
+     * with it. That keeps `What.Name` valid even though some targets (such as Case) have no `Name` field.
+     *
+     * Which SObjects are declared is TypeScript's to find out, through the SObjects' registry, so the
+     * relationship's type follows the definitions as they come and go:
+     *
+     * ```ts
+     * R extends { "account": infer T0 } ? R extends { "case": infer T1 }
+     *   ? R extends { "name": infer N } ? N & (T0 | T1) : T0 | T1
+     *   : sobject : sobject
+     * ```
+     */
+    #polymorphicType(targets, sobject) {
+        const registry = this.#resolver.sobjectsRegistry;
+        const union = targets.map((_, i) => `T${i}`).join(" | ");
+        let type = `${registry} extends { "name": infer N } ? N & (${union}) : ${union}`;
+        for (let i = targets.length - 1; i >= 0; i--) {
+            type = `${registry} extends { ${JSON.stringify(targets[i].toLowerCase())}: infer T${i} } ? ${type} : ${sobject}`;
+        }
+        return type;
+    }
+    #getMethodParameters(node) {
+        const params = new Map();
+        const parameters = node.childForFieldName("parameters");
+        if (!parameters) {
+            return params;
+        }
+        for (const p of parameters.namedChildren) {
+            const name = p.childForFieldName("name")?.text;
+            if (name !== undefined) {
+                params.set(name, this.#getType(p.childForFieldName("type")));
+            }
+        }
+        return params;
+    }
+    /**
+     * Writes a static `@AuraEnabled` method's module: `@salesforce/apex/<Class>.<method>` (or
+     * `@salesforce/apexContinuation/...` for a continuation), whose default export LWC calls imperatively
+     * and, when it's cacheable, wires (its `adapter`).
+     */
+    #writeMethodModule({ nameNode, returnType, params, cacheable, continuation, doc, signature }) {
+        const builder = this.#builder;
+        const name = nameNode.text;
+        // `@param` docs are repeated on the parameter object's properties, which is where editors show them
+        const paramType = `{ ${Array.from(params.entries())
+            .map(([param, type]) => {
+            const paramDoc = doc?.params.get(param.toLowerCase());
+            return `${paramDoc ? `/** ${inlineDoc(paramDoc)} */ ` : ""}${param}: ${type}`;
+        })
+            .join("; ")} }`;
+        const packagePrefix = this.#packageNamespace === undefined ? "" : `${this.#packageNamespace}.`;
+        const module = `@salesforce/apex${continuation ? "Continuation" : ""}/${packagePrefix}${this.#classNameNode.text}.${name}`;
+        const docLines = docParagraphs(signature === undefined ? undefined : ["---", "**Apex**", "", "```apex", signature, "```"], doc?.lines ?? []);
+        builder.write("declare module ");
+        builder.write(JSON.stringify(module), nameNode.startIndex, nameNode.endIndex);
+        builder.write(` {\n${jsDoc("  ", docLines)}  const `);
+        builder.write(name, nameNode.startIndex, nameNode.endIndex);
+        builder.write(`: {\n    (${params.size === 0 ? "" : `param: ${paramType}`}): Promise<${returnType}>;`);
+        if (cacheable) {
+            // only cacheable Apex can be wired; the adapter is the WireAdapterConstructor `@wire` takes
+            builder.write(`
+    adapter: import("lwc").WireAdapterConstructor<
+      ${params.size === 0 ? "never" : paramType},
+      { error?: unknown; data?: ${returnType}; }
+    >;`);
+        }
+        builder.write(`\n  };\n  export default ${name};\n}\n`);
+    }
+    /**
+     * The TypeScript type of an Apex type reference: `base` when it's a class's base class (see
+     * `TypeResolver.resolve`). A reference that's missing, as in a class being edited, is `unknown` (`{}`
+     * for a base class, since an interface can't extend `unknown`).
+     */
+    #getType(node, { base = false } = {}) {
+        const unknown = base ? "{}" : "unknown";
+        if (!node) {
+            return unknown;
+        }
+        switch (node.type) {
+            case "generic_type": {
+                // if generic type, see if it is a list or map
+                const genType = node.namedChildren[0]?.text ?? "";
+                const typeNode = node.namedChildren[1];
+                if (!typeNode) {
+                    return unknown;
+                }
+                switch (genType.toLowerCase()) {
+                    case "list":
+                    case "set": // sets serialize to JSON arrays
+                        return this.#getType(typeNode.namedChildren[0]) + "[]";
+                    case "map":
+                        // JSON object keys are strings, whatever the map's key type
+                        return `Record<string, ${this.#getType(typeNode.namedChildren[1])}>`;
+                    default:
+                        // another generic type (such as `Iterable<String>` or `Database.Batchable<SObject>`) is an
+                        // instance of whichever class implements it, so nothing is known about its value
+                        return unknown;
+                }
+            }
+            case "array_type": {
+                // `String[]` is the same as `List<String>`
+                const elementType = this.#getType(node.namedChildren[0]);
+                const dimensions = node.namedChildren[1]?.text.replace(/\s/g, "") ?? "[]";
+                return elementType + dimensions;
+            }
+            case "scoped_type_identifier":
+                // `a.b.c` nests one scoped identifier in another, so its parts come from its text
+                return this.#resolver.resolve(node.text.split(".").map((part) => part.trim()), { base });
+        }
+        const override = PRIMITIVE_TYPES[node.text.toLowerCase()];
+        if (override) {
+            return override;
+        }
+        return this.#resolver.resolve([node.text], { base });
+    }
+    /**
+     * Declares what the file's references need (see `TypeResolver.declarations`), and the file's own type
+     * in a registry: an SObject definition's in the SObjects', and a project class's in the project's when
+     * a library type has its name, which it shadows. A package's classes aren't the project's, so they
+     * don't shadow library types in its code.
+     */
+    #addLibraryDeclarations() {
+        const ownName = this.#classNameNode.text;
+        const ownRegistry = this.#isSobject
+            ? SOBJECTS_REGISTRY
+            : this.#packageNamespace === undefined && apexLibrary.hasTypeNamed(ownName)
+                ? CLASSES_REGISTRY
+                : undefined;
+        const declarations = this.#resolver.declarations(ownName, ownRegistry);
+        if (declarations !== "") {
+            this.#builder.write(declarations);
+        }
+    }
+}
+/**
+ * Finds the callback of a continuation method: the method of this class named by its
+ * `<continuation>.continuationMethod = '<name>'` assignment. Returns undefined when the method doesn't
+ * name exactly one callback with a string literal, or the class has no method of that name.
+ */
+function getContinuationCallback(methodNode, classMethods) {
+    const names = new Set();
+    for (const assignment of methodNode.childForFieldName("body")?.descendantsOfType("assignment_expression") ?? []) {
+        const left = assignment.childForFieldName("left");
+        const right = assignment.childForFieldName("right");
+        if (left?.type !== "field_access" || left.childForFieldName("field")?.text.toLowerCase() !== "continuationmethod") {
+            continue;
+        }
+        if (right?.type !== "string_literal") {
+            return undefined; // a callback chosen at runtime
+        }
+        // Apex method names are case-insensitive
+        names.add(right.text.slice(1, -1).toLowerCase());
+    }
+    if (names.size !== 1) {
+        return undefined;
+    }
+    const [name] = names;
+    return classMethods.find((m) => m !== methodNode && m.childForFieldName("name")?.text.toLowerCase() === name);
+}
+/**
+ * A declaration's own modifiers (such as `static` or `global`, lower-cased, as Apex's are
+ * case-insensitive) and its `@AuraEnabled` annotation, if it has one; not those of what it contains (such
+ * as a method's body). Read in one pass, since each node read crosses into the parser's WebAssembly.
+ */
+function declarationModifiers(node) {
+    const modifiers = new Set();
+    let auraEnabled;
+    for (const child of node.namedChildren) {
+        if (child.type !== "modifiers") {
+            continue;
+        }
+        for (const modifier of child.namedChildren) {
+            if (modifier.type === "modifier") {
+                modifiers.add(modifier.text.toLowerCase());
+            }
+            else if (auraEnabled === undefined &&
+                modifier.type === "annotation" &&
+                modifier.childForFieldName("name")?.text.toLowerCase() === "auraenabled") {
+                auraEnabled = modifier;
+            }
+        }
+    }
+    return { modifiers, auraEnabled };
+}
+/**
+ * A method's Apex signature, shown in its module's documentation: its return type, name and parameters
+ * (`List<SalesOrderDto> getRecentOrders(Integer maxResults)`), without its annotations and modifiers.
+ */
+function apexSignature(methodNode) {
+    const type = methodNode.childForFieldName("type");
+    const name = methodNode.childForFieldName("name");
+    if (!type || !name) {
+        return undefined;
+    }
+    const parameters = (methodNode.childForFieldName("parameters")?.namedChildren ?? []).map((p) => [p.childForFieldName("type"), p.childForFieldName("name")].map((node) => typeText(node?.text ?? "")).join(" "));
+    return `${typeText(type.text)} ${name.text}(${parameters.join(", ")})`;
+}
+/** A type's text on one line, spaced like `Map<String, List<Account>>`. */
+function typeText(text) {
+    return text
+        .replace(/\s+/g, " ")
+        .replace(/\s*([<>[\]])\s*/g, "$1")
+        .replace(/\s*,\s*/g, ", ")
+        .trim();
+}
+/** Whether an annotation sets `key` to true, as in `@AuraEnabled(cacheable=true)` (case-insensitive). */
+function annotationFlag(annotation, key) {
+    return (annotation.childForFieldName("arguments")?.descendantsOfType("annotation_key_value") ?? []).some((pair) => pair.childForFieldName("key")?.text.toLowerCase() === key && pair.childForFieldName("value")?.text.toLowerCase() === "true");
+}

package/dist/apex/library.config.d.ts

@@ -0,0 +1,23 @@
+import type { LibraryType } from "./library.ts";
+export interface ApexNamespaceConfig {
+    /** The namespace's name, as Apex and the StandardApexLibrary folder spell it. */
+    readonly name: string;
+    /**
+     * Whether the project's SObjects belong to this namespace, as they do to Schema. Where the namespace
+     * comes in an unqualified name's resolution, an SObject of that name is found there.
+     */
+    readonly sobjects?: boolean;
+}
+export interface ApexLibraryConfig {
+    /**
+     * The namespaces, in the order an unqualified name (such as `Exception`) is looked for in them. The
+     * project's own types come before all of them, so a project class shadows a library type of the same
+     * name, which then needs its namespace (`System.Exception`).
+     */
+    readonly namespaces: readonly ApexNamespaceConfig[];
+    /** Names (case-insensitive) looked for in a different order of namespaces than `namespaces` gives. */
+    readonly resolutionOrder: Readonly<Record<string, readonly string[]>>;
+    /** Types the StandardApexLibrary leaves out, by namespace and name. They're added to the generated ones. */
+    readonly additionalTypes: Readonly<Record<string, Readonly<Record<string, LibraryType>>>>;
+}
+export declare const APEX_LIBRARY_CONFIG: ApexLibraryConfig;

package/dist/apex/library.config.js

@@ -0,0 +1,17 @@
+export const APEX_LIBRARY_CONFIG = {
+    namespaces: [{ name: "Schema", sobjects: true }, { name: "System" }],
+    resolutionOrder: {
+        // Unqualified, these are the compound field types, even in an org with the Address and Location
+        // objects, which need `Schema.Address` and `Schema.Location` (as System.Address's and
+        // System.Location's documentation says). The SObject definitions use them for compound fields.
+        address: ["System", "Schema"],
+        location: ["System", "Schema"],
+    },
+    additionalTypes: {
+        System: {
+            // the base of every exception, built into the language
+            Exception: { kind: "class" },
+            AuraHandledException: { kind: "class", extends: "System.Exception" },
+        },
+    },
+};