cocolabs / pz-zdoc Goto Github PK

Gradle distribution tasks should create a functional application launch script for Windows platform.

Many dependencies used by ZomboidDoc require inclusion of license notices.

Make all line separators platform-independent (should work on Windows/Unix/Mac).
Initial thoughts are that all instances of \n should be replaced with System.lineSeparator().

Gradle distribution tasks should create a functional application launch script for Unix platforms.

Distribution is logging to a single log file created in the application root directory on every session. Production logging should use the same system as development, only with a lower logging level.

Project jar fails to execute compile task due to RuntimeException thrown:

Exception in thread "main" java.lang.IllegalArgumentException: URI is not hierarchical
        at java.io.File.<init>(File.java:418)
        at io.yooksi.pz.zdoc.util.Utils.getProperties(Utils.java:112)
        at io.yooksi.pz.zdoc.Main.main(Main.java:207)

Release tags are created before issues contained in related release are closed on Github. This is incorrect workflow practice, and has unintended consequences such as making it difficult to create automated changelogs (joffrey-bion/gradle-github-changelog#30).

The solution is to change tag timestamps to place the tag chronologically just after the release merge commit.

Parsing method that have been marked as deprecated will throw an exception.

Deprecated methods (such as ScriptManager#LoadFilePP) have a signature that starts with @Deprecated:

@Deprecated
public void LoadFilePP(java.lang.String filename, boolean bLoadJar)
                             throws java.io.FileNotFoundException, 
                             java.io.UnsupportedEncodingException

Compiled lua functions need to be formatted as syntactic sugar to properly represent Java methods.

In the current version the application is extrapolating which classes are exposed by reading methods declared in LuaManager#GlobalObject or more precisely their parameters and return values.

While it is true that class references used in exposed global methods are going to be exposed themselves, just collecting these references does not encompass all exposed classes. The only way to do that is to obtain it programmatically from code.

All exposed classes are stored as Class<?> objects in HashSet exposed variable in a private inner class LuaManager#Exposer. We need to add Zomboid classes and libraries to application classpath and employ reflection to read these objects.

Add optional switches for printing game and project version.

Parsing method parameter signatures that contain varargs throws an exception.

• Method signature:
  sendObjectChange(java.lang.String change, java.lang.Object... args)

• Exception thrown:

  Excluding method (public void sendObjectChange(java.lang.String change, java.lang.Object... args)) from detail - 
  Failed to parse signature "java.lang.String change, java.lang.Object... args" (Unknown class: java.lang.Object...).

For example files that contain only comments are not recognized as empty files and are still parsed and written as empty files.

The project should be migrated from Jitpack over to Github Packages.

Hey yooksi,
i do not understand your installation tutorial. May you help me with that issue :).

Application is unable to create needed output directory structure.

Exception in thread "main" java.io.IOException: Unable to create output directory: build\generated\sources\zdoc\lua
	at io.yooksi.pz.zdoc.Main.validateLuaOutputPath(Main.java:206)
	at io.yooksi.pz.zdoc.Main.main(Main.java:101)

Method used to create the structure should be mkdirs() instead of mkdir().

The following classes that were removed from JDK 11 are required by JavaCompiler when reading declared classes:

sun.misc.Lock
javax/xml/bind/JAXBException

Here are possible workarounds for this issue:

• Find a way to include missing classes on compiler classpath.
• Downgrade project Java version to 1.8.
• Exclude the classes affected by this issue from compilation

This problem affects the following Zomboid classes:

zombie.core.skinnedmodel.population.HairStyles
zombie.core.skinnedmodel.population.BeardStyles
zombie.chat.ChatBase

Github CI build failed due to missing project property.

FAILURE: Build failed with an exception.

• Where:
  Script '/home/runner/work/pz-zdoc/pz-zdoc/setup.gradle' line: 38

• What went wrong:
  A problem occurred evaluating script.
  > Unable to find local project property game.dir

MethodDetail should read class methods that are overriding methods from superclass.

This is currently not happening because those methods are not listen in the API detail documentation section.
Inherited methods are found listed in methods.inherited.from.class... table.

Here is a list of libraries included in the distribution that are not needed during runtime:

+--- com.google.guava:guava:30.1-jre
|    +--- com.google.guava:failureaccess:1.0.1
|    +--- com.google.guava:listenablefuture:9999.0-empty-to-avoid-conflict-with-guava
|    +--- com.google.code.findbugs:jsr305:3.0.2
|    +--- org.checkerframework:checker-qual:3.5.0
|    +--- com.google.errorprone:error_prone_annotations:2.3.4
|    \--- com.google.j2objc:j2objc-annotations:1.3

Library jar archive should be generated with a correct game version classifier.

For example: zdoc-lua-41.50-IWBUMS

It's time for this project to start keeping a changelog.

We can automate this by using github-changelog-generator.

Lua compiler is compiling synthetic constructs as normal members.

---@param arg0 ArrayList|Unknown
---@return int
function ArrayList:access$000(arg0) end

The IDEA issue that randomly deletes the .name file has still not been resolved:
https://youtrack.jetbrains.com/issue/IDEA-153554

It would be best to remove this file from VCS until it has been resolved.

FOSSA is an online service that helps automatically track, manage, and remediate issues with the open source projects.

Use FOSSA Action to integrate FOSSA in CD workflow.

When launching the game using windows launch script the Java distribution shipped with Project Zomboid is ignored.
This is caused by line 99 in winScriptTemplate.bat that always reads version from JAVA_HOME.

Use codecov-actions action to upload coverage reports from Github Actions.

Test logging level should be configurable via system properties (environment variables). This is especially important for Github Action workflows that are currently producing more then 13MB of test log data on each run. Standard test runs should either have logging disabled or set to info level where they will produce little to none log data. Then when tests fail on server we can re-run them with higher log level to see what went wrong, the output of unit tests should be deterministic.

Functions in LuaManager_GlobalObject should not be defined through a table.

This exception is thrown when running integration test:
shouldNotThrowClassNotFoundExceptionWhenReadingExposedJavaClasses

java.lang.VerifyError: Bad return type
Exception Details:
  Location:
    zombie/iso/IsoObject.factoryFromFileInput(Lzombie/iso/IsoCell;I)Lzombie/iso/IsoObject; @37: areturn
  Reason:
    Type 'zombie/characters/IsoPlayer' (current frame, stack[0]) is not assignable to 'zombie/iso/IsoObject' (from method signature)
  Current Frame:
    bci: @37
    flags: { }
    locals: { 'zombie/iso/IsoCell', integer }
    stack: { 'zombie/characters/IsoPlayer' }
  Bytecode:
    0x0000000: 1b12 42b6 0043 a000 0eb8 0044 4d2c 0bb5
    0x0000010: 0045 2cb0 1b12 46b6 0043 a000 0cbb 0006
    0x0000020: 592a b700 47b0 1b12 48b6 0043 a000 0cbb
    0x0000030: 0049 592a b700 4ab0 1b12 4bb6 0043 a000
    0x0000040: 0cbb 004c 592a b700 4db0 1b12 4eb6 0043
    0x0000050: a000 0cbb 004f 592a b700 50b0 1b12 51b6
    0x0000060: 0043 a000 0cbb 0052 592a b700 53b0 1b12
    0x0000070: 54b6 0043 a000 0cbb 0055 592a b700 56b0
    0x0000080: 1b12 57b6 0043 a000 0cbb 0058 592a b700
    0x0000090: 59b0 1b12 5ab6 0043 a000 0cbb 005b 592a
    0x00000a0: b700 5cb0 1b12 5db6 0043 a000 0cbb 005e
    0x00000b0: 592a b700 5fb0 1b12 60b6 0043 a000 0cbb
    0x00000c0: 0061 592a b700 62b0 1b12 63b6 0043 a000
    0x00000d0: 0cbb 0064 592a b700 65b0 1b12 66b6 0043
    0x00000e0: a000 0cbb 0067 592a b700 68b0 1b12 69b6
    0x00000f0: 0043 a000 0cbb 006a 592a b700 6bb0 1b12
    0x0000100: 6cb6 0043 a000 0cbb 006d 592a b700 6eb0
    0x0000110: 1b12 6fb6 0043 a000 0cbb 0070 592a b700
    0x0000120: 71b0 1b12 72b6 0043 a000 0cbb 0073 592a
    0x0000130: b700 74b0 1b12 75b6 0043 a000 0cbb 0076
    0x0000140: 592a b700 77b0 1b12 78b6 0043 a000 0cbb
    0x0000150: 0079 592a b700 7ab0 1b12 7bb6 0043 a000
    0x0000160: 0cbb 007c 592a b700 7db0 1b12 7eb6 0043
    0x0000170: a000 0cbb 007f 592a b700 80b0 1b12 81b6
    0x0000180: 0043 a000 0cbb 0082 592a b700 83b0 1b12
    0x0000190: 84b6 0043 a000 0cbb 0085 592a b700 86b0
    0x00001a0: 1b12 87b6 0043 a000 0cbb 0088 592a b700
    0x00001b0: 89b0 1b12 8ab6 0043 a000 0cbb 008b 592a
    0x00001c0: b700 8cb0 1b12 8db6 0043 a000 0cbb 008e
    0x00001d0: 592a b700 8fb0 1b12 90b6 0043 a000 0cbb
    0x00001e0: 0091 592a b700 92b0 1b12 5ab6 0043 a000
    0x00001f0: 0cbb 005b 592a b700 5cb0 1b12 93b6 0043
    0x0000200: a000 0cbb 0094 592a b700 95b0 1b12 96b6
    0x0000210: 0043 a000 07b8 0097 b01b 1298 b600 43a0
    0x0000220: 000c bb00 9959 2ab7 009a b01b 129b b600
    0x0000230: 43a0 000c bb00 9c59 2ab7 009d b01b 129e
    0x0000240: b600 43a0 000c bb00 9f59 2ab7 00a0 b01b
    0x0000250: 12a1 b600 43a0 000c bb00 a259 2ab7 00a3
    0x0000260: b01b 12a4 b600 43a0 0012 b200 a59a 000c
    0x0000270: bb00 a659 2ab7 00a7 b0bb 003a 592a b700
    0x0000280: a84d 2cb0                              
  Stackmap Table:
    same_frame(@20)
    same_frame(@38)
    same_frame(@56)
    same_frame(@74)
    same_frame(@92)
    same_frame(@110)
    same_frame(@128)
    same_frame(@146)
    same_frame(@164)
    same_frame(@182)
    same_frame(@200)
    same_frame(@218)
    same_frame(@236)
    same_frame(@254)
    same_frame(@272)
    same_frame(@290)
    same_frame(@308)
    same_frame(@326)
    same_frame(@344)
    same_frame(@362)
    same_frame(@380)
    same_frame(@398)
    same_frame(@416)
    same_frame(@434)
    same_frame(@452)
    same_frame(@470)
    same_frame(@488)
    same_frame(@506)
    same_frame(@524)
    same_frame(@537)
    same_frame(@555)
    same_frame(@573)
    same_frame(@591)
    same_frame(@609)
    same_frame(@633)

Implement an optional command option to package compiled library in an archive.

Logger output file pz-zdoc.log keeps getting created even when we don't use the StandardFile logger.
Either the logger system needs to be simplified to exclude standard logging or the file needs to be deleted on app exit.

Project distribution release creation process should be automated with Github Actions.

Using Github would be the ideal way to test and store project artifacts.

Command

pz-zdoc.bat annotate -i "E:\Games\Steam\steamapps\common\ProjectZomboid\media\lua\" -o "..\media\lua"

The same command does not throw an exception when the input path option value does not end with \.

Exception

Exception in thread "main" org.apache.commons.cli.MissingOptionException: Missing required option: o
        at org.apache.commons.cli.DefaultParser.checkRequiredOptions(DefaultParser.java:199)
        at org.apache.commons.cli.DefaultParser.parse(DefaultParser.java:130)
        at io.yooksi.pz.zdoc.cmd.CommandParser.parse(CommandParser.java:46)
        at io.yooksi.pz.zdoc.cmd.CommandParser.parse(CommandParser.java:26)
        at org.apache.commons.cli.DefaultParser.parse(DefaultParser.java:76)
        at io.yooksi.pz.zdoc.cmd.CommandParser.parse(CommandParser.java:40)
        at io.yooksi.pz.zdoc.cmd.CommandParser.parse(CommandParser.java:26)
        at org.apache.commons.cli.DefaultParser.parse(DefaultParser.java:60)
        at io.yooksi.pz.zdoc.cmd.CommandParser.parse(CommandParser.java:30)
        at io.yooksi.pz.zdoc.cmd.CommandLine.parse(CommandLine.java:49)
        at io.yooksi.pz.zdoc.Main.main(Main.java:92)

Assembled distributions on CI should have an up-to-date changelog.

Lua class names should follow the official Lua lexical conventions:

Names (also called identifiers) in Lua can be any string of Latin letters, Arabic-Indic digits, and underscores, not beginning with a digit and not being a reserved word. Identifiers are used to name variables, table fields, and labels.

Read more from Lua 5.4 Reference Manual: Lexical Conventions.

JavaCompilerTest tests fail when running with Gradle.

JavaCompilerTest > shouldCompileDeclaredJavaFieldsFromClassWithNullDocument() FAILED
    org.opentest4j.AssertionFailedError: expected: <[public float a, private final java.lang.Integer b, protected static final zombie.core.Color black, static zomb
ie.core.Color[] blue, public java.util.ArrayList cyan]> but was: <[public float a, private final java.lang.Integer b, protected static final zombie.core.Color blac
k, static zombie.core.Color[] blue, public java.util.ArrayList cyan, private static boolean[] $jacocoData]>
        at org.junit.jupiter.api.AssertionUtils.fail(AssertionUtils.java:55)
        at org.junit.jupiter.api.AssertionUtils.failNotEqual(AssertionUtils.java:62)
        at org.junit.jupiter.api.AssertEquals.assertEquals(AssertEquals.java:182)
        at org.junit.jupiter.api.AssertEquals.assertEquals(AssertEquals.java:177)
        at org.junit.jupiter.api.Assertions.assertEquals(Assertions.java:1124)
        at io.yooksi.pz.zdoc.compile.JavaCompilerTest.shouldCompileDeclaredJavaFieldsFromClassWithNullDocument(JavaCompilerTest.java:67)
Running test: Test shouldCompileDeclaredJavaFieldsFromClassWithDocument()(io.yooksi.pz.zdoc.compile.JavaCompilerTest)

JavaCompilerTest > shouldCompileDeclaredJavaFieldsFromClassWithDocument() FAILED
    org.opentest4j.AssertionFailedError: expected: <[public float a, private final java.lang.Integer b, protected static final zombie.core.Color black, static zomb
ie.core.Color[] blue, public java.util.ArrayList cyan]> but was: <[public float a, private final java.lang.Integer b, protected static final zombie.core.Color blac
k, static zombie.core.Color[] blue, public java.util.ArrayList cyan, private static boolean[] $jacocoData]>
        at org.junit.jupiter.api.AssertionUtils.fail(AssertionUtils.java:55)
        at org.junit.jupiter.api.AssertionUtils.failNotEqual(AssertionUtils.java:62)
        at org.junit.jupiter.api.AssertEquals.assertEquals(AssertEquals.java:182)
        at org.junit.jupiter.api.AssertEquals.assertEquals(AssertEquals.java:177)
        at org.junit.jupiter.api.Assertions.assertEquals(Assertions.java:1124)
        at io.yooksi.pz.zdoc.compile.JavaCompilerTest.shouldCompileDeclaredJavaFieldsFromClassWithDocument(JavaCompilerTest.java:90)
Running test: Test shouldCompileDeclaredJavaMethodsFromClassWithDocument()(io.yooksi.pz.zdoc.compile.JavaCompilerTest)

JavaCompilerTest > shouldCompileDeclaredJavaMethodsFromClassWithDocument() FAILED
    org.opentest4j.AssertionFailedError: expected: <[static void update(java.util.ArrayList<java.lang.String> params), static java.util.ArrayList<java.lang.String>
 getActivatedMods(), private static final java.lang.String init(java.lang.String object, java.lang.String[] params), protected static boolean DoesInstantly(int num
ber), public zombie.core.Color[] getColor(zombie.characters.IsoPlayer player), public int begin(java.lang.Object param),  java.lang.Object[] IsFinished()]> but was
: <[static void update(java.util.ArrayList<java.lang.String> params), static java.util.ArrayList<java.lang.String> getActivatedMods(), private static boolean[] $ja
cocoInit(), private static final java.lang.String init(java.lang.String object, java.lang.String[] params), protected static boolean DoesInstantly(int number), pub
lic zombie.core.Color[] getColor(zombie.characters.IsoPlayer player), public int begin(java.lang.Object param),  java.lang.Object[] IsFinished()]>
        at org.junit.jupiter.api.AssertionUtils.fail(AssertionUtils.java:55)
        at org.junit.jupiter.api.AssertionUtils.failNotEqual(AssertionUtils.java:62)
        at org.junit.jupiter.api.AssertEquals.assertEquals(AssertEquals.java:182)
        at org.junit.jupiter.api.AssertEquals.assertEquals(AssertEquals.java:177)
        at org.junit.jupiter.api.Assertions.assertEquals(Assertions.java:1124)
        at io.yooksi.pz.zdoc.compile.JavaCompilerTest.shouldCompileDeclaredJavaMethodsFromClassWithDocument(JavaCompilerTest.java:166)
Running test: Test shouldCompileDeclaredJavaMethodsFromClassWithNullDocument()(io.yooksi.pz.zdoc.compile.JavaCompilerTest)

JavaCompilerTest > shouldCompileDeclaredJavaMethodsFromClassWithNullDocument() FAILED
    org.opentest4j.AssertionFailedError: expected: <[static void update(java.util.ArrayList<?> arg0), public int begin(java.lang.Object arg0),  java.lang.Object[]
IsFinished(), public zombie.core.Color[] getColor(zombie.characters.IsoPlayer arg0), static java.util.ArrayList<?> getActivatedMods(), protected static boolean Doe
sInstantly(int arg0), private static final java.lang.String init(java.lang.String arg0, java.lang.String[] arg1)]> but was: <[static void update(java.util.ArrayLis
t<?> arg0), private static boolean[] $jacocoInit(), public int begin(java.lang.Object arg0),  java.lang.Object[] IsFinished(), public zombie.core.Color[] getColor(
zombie.characters.IsoPlayer arg0), static java.util.ArrayList<?> getActivatedMods(), protected static boolean DoesInstantly(int arg0), private static final java.la
ng.String init(java.lang.String arg0, java.lang.String[] arg1)]>
        at org.junit.jupiter.api.AssertionUtils.fail(AssertionUtils.java:55)
        at org.junit.jupiter.api.AssertionUtils.failNotEqual(AssertionUtils.java:62)
        at org.junit.jupiter.api.AssertEquals.assertEquals(AssertEquals.java:182)
        at org.junit.jupiter.api.AssertEquals.assertEquals(AssertEquals.java:177)
        at org.junit.jupiter.api.Assertions.assertEquals(Assertions.java:1124)

LuaAnnotator and LuaCompiler are generating class names that conflict with each other.

This is not a code bug, but an oversight of game Lua and Java class naming compatibility.

EmmyLua param annotations hold incorrect parameter name when original name is reserved or built-in type.

---@public
---@param start float
---@param end float
---@param delta float
---@return float
function GameTime:Lerp(start, _end, delta) end

The code responsible for this is in the LuaParameter constructor:

public LuaParameter(LuaType type, String name) {

	this.type = type;
	this.name = EmmyLua.getSafeLuaName(name);
	// name should be "this.name" (safe variation)
	this.annotations = Collections.singletonList(new EmmyLuaParam(name, type));
}

Use Java JDK documentation to provide parameter names for JDK methods.

Make it easy for users to launch the application from game directory by automatically setting the PZ_DIR_PATH environment variable when the distribution directory is placed inside the game root directory.

This way of installing the application also allows the input and ouptut command options to be relative paths.

Annotate command should write only files that were actually annotated (ALL_INCLUDED and PARTIAL_INCLUSION).
There should be no need to include source Lua files that were not annotated, it's up to users to add source files as separate library.

Related to #25

There is too much logs being printed to console in production environment.

Method parseClassSignature fails to parse a signature that represents a parameterized type with 3 or more type parameters.

Improve README documentation to better communicate how the application should be used.
Clarify in particular what hyperlinks are acceptable as API input command argument (#4).

MethodDetail#parse() fails to parse method parameters with parametrized object types.

Lua compiler should compile LuaManager.GlobalObject methods.