Support d.ts patch overlays in gradle plugin

GenerateTypeScriptTask can now copy an optional patches directory into the generated output so manual overrides can ship alongside generated defs.

Converter tweaks: anchor method signature regex to line starts, and ensure generated (including nested) types include a @javaFqn tag for reliable mapping back to Java sources.
This commit is contained in:
bigguy345 committed 2026-02-03 07:04:50 +02:00
1 parent 074c780d50
commit 9e4692d8e4
4 files changed
+111 -15

No files matched your search

+4 -1
View File
@@ -3,4 +3,7 @@
/out
/bin
/.idea
/.vscode
/.vscode
/.settings
.project
.classpath
+25
View File
@@ -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/<modid>/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/<modid>/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<T> {
getDBCPlayer(): IDBCAddon;
}
```
@@ -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<String> 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<File> 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!")
@@ -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<String> 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<String> 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.