diff --git a/gradle-plugins/.gitignore b/gradle-plugins/.gitignore index 94cac27cf..22bff6717 100644 --- a/gradle-plugins/.gitignore +++ b/gradle-plugins/.gitignore @@ -3,4 +3,7 @@ /out /bin /.idea -/.vscode \ No newline at end of file +/.vscode +/.settings +.project +.classpath \ No newline at end of file diff --git a/gradle-plugins/README.md b/gradle-plugins/README.md index 78f1a1091..1e0e7fba2 100644 --- a/gradle-plugins/README.md +++ b/gradle-plugins/README.md @@ -60,6 +60,9 @@ tasks.named("generateTypeScriptDefinitions").configure { // Whether to clean old generated files before regenerating cleanOutputFirst = true + + // Optional: copy external patch .d.ts files into assets//api/patches + patchesDirectory = "dts-patches" } @@ -67,3 +70,25 @@ tasks.named("generateTypeScriptDefinitions").configure { // But in most cases, you may want to run the task manually when needed // processResources.dependsOn generateTypeScriptDefinitions ``` + +--- + +## Patches (optional overrides) + +Use `dts-patches/` to override or refine generated types. Files in this folder are copied to +`assets//api/patches` after generation. + +### Example: override `IPlayer.getDBCPlayer()` to return `IDBCAddon` instead of `IDBCPlayer` + +File: `dts-patches/IPlayer.d.ts` + +```ts +/** + * DBC Addon patch for IPlayer + * @javaFqn noppes.npcs.api.entity.IPlayer + */ +export interface IPlayer { + getDBCPlayer(): IDBCAddon; +} +``` + diff --git a/gradle-plugins/src/main/groovy/dts/GenerateTypeScriptTask.groovy b/gradle-plugins/src/main/groovy/dts/GenerateTypeScriptTask.groovy index 31a06c609..b62e6cedc 100644 --- a/gradle-plugins/src/main/groovy/dts/GenerateTypeScriptTask.groovy +++ b/gradle-plugins/src/main/groovy/dts/GenerateTypeScriptTask.groovy @@ -3,11 +3,11 @@ package dts import org.gradle.api.DefaultTask import org.gradle.api.tasks.TaskAction import org.gradle.api.tasks.Input +import org.gradle.api.tasks.InputDirectory import org.gradle.api.tasks.InputFiles import org.gradle.api.tasks.OutputDirectory import org.gradle.api.tasks.Internal import org.gradle.api.tasks.Optional -import org.gradle.api.file.FileCollection /** * Gradle task that generates TypeScript definition (.d.ts) files from Java API sources. @@ -37,6 +37,9 @@ abstract class GenerateTypeScriptTask extends DefaultTask { @Input List excludePatterns = [] + + @Internal + Object patchesDirectory // Provide task input/output properties that Gradle can validate @InputFiles @@ -71,6 +74,24 @@ abstract class GenerateTypeScriptTask extends DefaultTask { } return f } + + @Optional + @InputDirectory + protected File getResolvedDtsPatchesDirectory() { + if (patchesDirectory == null) return null + def obj = patchesDirectory + if (obj instanceof File) return obj + String pathStr = obj.toString() + if (pathStr.contains('${modid}')) { + String modid = project.archivesBaseName ?: 'mod' + pathStr = pathStr.replace('${modid}', modid) + } + File f = new File(pathStr) + if (!f.isAbsolute()) { + f = new File(project.projectDir, pathStr) + } + return f + } /** * Converts a value (String or File) to a File object. @@ -87,6 +108,7 @@ abstract class GenerateTypeScriptTask extends DefaultTask { void generate() { List srcDirs = getResolvedSourceDirectories() File outDir = getResolvedOutputDirectory() + File patchesDir = getResolvedDtsPatchesDirectory() logger.lifecycle("=".multiply(60)) logger.lifecycle("Generating TypeScript definitions...") @@ -129,6 +151,22 @@ abstract class GenerateTypeScriptTask extends DefaultTask { } converter.processDirectories(validDirs, logger) + + if (patchesDir != null) { + if (!patchesDir.exists()) { + logger.lifecycle("Patches directory does not exist: ${patchesDir}") + } else { + File patchOutputDir = new File(outDir, "patches") + if (patchOutputDir.exists()) { + patchOutputDir.deleteDir() + } + project.copy { + from patchesDir + into patchOutputDir + } + logger.lifecycle("Copied .d.ts patches to: ${patchOutputDir}") + } + } logger.lifecycle("=".multiply(60)) logger.lifecycle("TypeScript definition generation complete!") diff --git a/gradle-plugins/src/main/groovy/dts/JavaToTypeScriptConverter.groovy b/gradle-plugins/src/main/groovy/dts/JavaToTypeScriptConverter.groovy index 16d71bc90..9d96633ed 100644 --- a/gradle-plugins/src/main/groovy/dts/JavaToTypeScriptConverter.groovy +++ b/gradle-plugins/src/main/groovy/dts/JavaToTypeScriptConverter.groovy @@ -334,8 +334,9 @@ class JavaToTypeScriptConverter { String topLevelBody = removeNestedTypeBodies(body) // Match method signatures - handles complex generics + // Anchored with (?m)^ to prevent matching inside // comment lines // Capture JSDoc in group 1, returnType in group 2, methodName in group 3, params in group 4 - def methodPattern = ~/(\/\*\*[\s\S]*?\*\/\s*)?(?:@\w+(?:\([^)]*\))?\s*)*(?:public\s+|protected\s+|private\s+)?(?:static\s+)?(?:abstract\s+)?(?:default\s+)?(?:synchronized\s+)?(?:final\s+)?(?:<[^>]+>\s+)?(\w[\w.<>,\[\]\s]*?)\s+(\w+)\s*\(([^)]*)\)\s*(?:throws\s+[\w,\s]+)?[;{]/ + def methodPattern = ~/(?m)^\s*(\/\*\*[\s\S]*?\*\/\s*)?(?:@\w+(?:\([^)]*\))?\s*)*(?:public\s+|protected\s+|private\s+)?(?:static\s+)?(?:abstract\s+)?(?:default\s+)?(?:synchronized\s+)?(?:final\s+)?(?:<[^>]+>\s+)?(\w[\w.<>,\[\]\s]*?)\s+(\w+)\s*\(([^)]*)\)\s*(?:throws\s+[\w,\s]+)?[;{]/ def matcher = topLevelBody =~ methodPattern while (matcher.find()) { @@ -542,8 +543,10 @@ class JavaToTypeScriptConverter { Set typeParamNames = type.parsedTypeParams?.collect { it.name }?.toSet() ?: [] as Set // JSDoc - if (type.jsdoc) { - sb.append(convertJsDoc(type.jsdoc, indent)) + String javaFqn = buildJavaFqn(parsed.packageName, type.name) + String typeJsDoc = ensureJavaFqnTag(type.jsdoc, javaFqn, indent) + if (typeJsDoc) { + sb.append(typeJsDoc) sb.append('\n') } @@ -581,7 +584,7 @@ class JavaToTypeScriptConverter { type.nestedTypes.each { nested -> // Always generate as interface, even if empty // Empty interfaces with extends are important for type hierarchy - generateNestedType(sb, nested, type.name, parsed, currentPath, indent + ' ') + generateNestedType(sb, nested, type.name, type.name, parsed, currentPath, indent + ' ') } sb.append("${indent}}\n") } @@ -592,13 +595,16 @@ class JavaToTypeScriptConverter { * Generate a nested type (interface/class within a namespace) * Recursively handles nested types that themselves have nested types */ - private void generateNestedType(StringBuilder sb, JavaType type, String parentTypeName, ParsedJavaFile parsed, String currentPath, String indent) { + private void generateNestedType(StringBuilder sb, JavaType type, String parentTypeName, String parentTypeChain, ParsedJavaFile parsed, String currentPath, String indent) { // Build a set of type parameter names for this nested type Set typeParamNames = type.parsedTypeParams?.collect { it.name }?.toSet() ?: [] as Set // JSDoc - if (type.jsdoc) { - sb.append(convertJsDoc(type.jsdoc, indent)) + String nestedChain = parentTypeChain ? "${parentTypeChain}.${type.name}" : type.name + String javaFqn = buildJavaFqn(parsed.packageName, nestedChain) + String nestedJsDoc = ensureJavaFqnTag(type.jsdoc, javaFqn, indent) + if (nestedJsDoc) { + sb.append(nestedJsDoc) sb.append('\n') } @@ -632,7 +638,7 @@ class JavaToTypeScriptConverter { type.nestedTypes.each { nested -> // Always generate as interface, even if empty // Empty interfaces with extends are important for type hierarchy - generateNestedType(sb, nested, type.name, parsed, currentPath, indent + ' ') + generateNestedType(sb, nested, type.name, nestedChain, parsed, currentPath, indent + ' ') } sb.append("${indent}}\n") } @@ -717,11 +723,6 @@ class JavaToTypeScriptConverter { return convertGenericType(javaType, parsed, currentPath, typeParamNames) } - // Handle functional interfaces from java.util.function - if (FUNCTIONAL_MAPPINGS.containsKey(javaType)) { - return 'Function' // Simplified - will be expanded in generic handling - } - // Check if it is an API type (needs import) String importPath = resolveImportPath(javaType, parsed, currentPath) if (importPath != null) { @@ -1005,6 +1006,35 @@ class JavaToTypeScriptConverter { } }.join('\n') } + + private String ensureJavaFqnTag(String jsdoc, String javaFqn, String indent) { + if (javaFqn == null || javaFqn.isEmpty()) { + return convertJsDoc(jsdoc, indent) + } + + if (jsdoc != null && jsdoc.contains('@javaFqn')) { + return convertJsDoc(jsdoc, indent) + } + + if (jsdoc == null || jsdoc.trim().isEmpty()) { + return "${indent}/**\n${indent} * @javaFqn ${javaFqn}\n${indent} */" + } + + String converted = convertJsDoc(jsdoc, indent) + int endIndex = converted.lastIndexOf('*/') + if (endIndex >= 0) { + String insert = "${indent} * @javaFqn ${javaFqn}\n" + return converted.substring(0, endIndex) + insert + converted.substring(endIndex) + } + + return converted + "\n${indent} * @javaFqn ${javaFqn}" + } + + private String buildJavaFqn(String packageName, String typeName) { + if (typeName == null || typeName.isEmpty()) return null + if (packageName == null || packageName.isEmpty()) return typeName + return packageName + '.' + typeName + } /** * Extract @hookName value from a JSDoc comment.