├── settings.gradle ├── annotations └── src │ └── main │ ├── resources │ └── META-INF │ │ └── services │ │ └── javax.annotation.processing.Processor │ └── java │ └── net │ └── kumbhar │ └── dx │ ├── Hacks.java │ ├── Hack.java │ └── HackChecker.java ├── .gitignore ├── tests └── src │ └── main │ └── java │ └── net │ └── kumbhar │ └── dx │ └── HacksTest.java ├── LICENSE ├── gradlew.bat ├── README.md └── gradlew /settings.gradle: -------------------------------------------------------------------------------- 1 | rootProject.name = 'record-hacks' 2 | 3 | include 'annotations', 'tests' 4 | -------------------------------------------------------------------------------- /annotations/src/main/resources/META-INF/services/javax.annotation.processing.Processor: -------------------------------------------------------------------------------- 1 | net.kumbhar.dx.HackChecker -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | build 2 | target 3 | .idea 4 | gradle 5 | .gradle 6 | *.class 7 | *.iml 8 | *.ipr 9 | gradle.properties 10 | -------------------------------------------------------------------------------- /annotations/src/main/java/net/kumbhar/dx/Hacks.java: -------------------------------------------------------------------------------- 1 | package net.kumbhar.dx; 2 | 3 | import java.lang.annotation.ElementType; 4 | import java.lang.annotation.Retention; 5 | import java.lang.annotation.RetentionPolicy; 6 | import java.lang.annotation.Target; 7 | 8 | @Retention(RetentionPolicy.SOURCE) 9 | @Target({ElementType.FIELD, 10 | ElementType.CONSTRUCTOR, 11 | ElementType.TYPE, 12 | ElementType.ANNOTATION_TYPE, 13 | ElementType.LOCAL_VARIABLE, 14 | ElementType.METHOD, 15 | ElementType.PARAMETER}) 16 | public @interface Hacks { 17 | Hack[] value(); 18 | } 19 | -------------------------------------------------------------------------------- /tests/src/main/java/net/kumbhar/dx/HacksTest.java: -------------------------------------------------------------------------------- 1 | package net.kumbhar.dx; 2 | 3 | import java.util.Map; 4 | 5 | public class HacksTest { 6 | 7 | @Hack(description = "This should really have the correct type but we dont know what it is.") 8 | private Object fieldUsage; 9 | 10 | 11 | @Hack(description = "This is a hack that will make my life miserable in 1 month") 12 | @Hack(description = "This is a hack that will make my life miserable in 2 months") 13 | public void repeatedUsage() { 14 | // Ignore 15 | } 16 | 17 | @Hack(description = "This hack needed to be fixed yesterday", fixBeforeDate = "2019-07-14") 18 | public void buildFailureUsage() { 19 | // Ignore 20 | } 21 | 22 | public void methodParameterUsage(@Hack(description = "This should be its own type") Map data) { 23 | // Ignore 24 | } 25 | 26 | public void localvariableUsage() { 27 | @Hack(description = "We have decided to not follow best practices for now") 28 | boolean followBestPractices = false; 29 | } 30 | 31 | } 32 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | MIT License 2 | 3 | Copyright (c) 2019 rohitkumbhar 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | -------------------------------------------------------------------------------- /annotations/src/main/java/net/kumbhar/dx/Hack.java: -------------------------------------------------------------------------------- 1 | package net.kumbhar.dx; 2 | 3 | import java.lang.annotation.*; 4 | 5 | @Repeatable(Hacks.class) 6 | @Retention(RetentionPolicy.SOURCE) 7 | @Target({ElementType.FIELD, 8 | ElementType.CONSTRUCTOR, 9 | ElementType.TYPE, 10 | ElementType.ANNOTATION_TYPE, 11 | ElementType.LOCAL_VARIABLE, 12 | ElementType.METHOD, 13 | ElementType.PARAMETER}) 14 | /* 15 | * An annotation that denotes a "creative solution" in code. 16 | */ 17 | public @interface Hack { 18 | 19 | /** 20 | * Description of this creative solution. Generally speaking, this should document the necessity of this hack 21 | * and what can be done to remove it. 22 | * 23 | * @return Description of the hack 24 | */ 25 | String description(); 26 | 27 | /** 28 | * Optional: A link or identifier to any bug tracking system that has an item to fix this hack, eventually, of course. 29 | * 30 | * @return A url or key in a bug tracker e.g. https://jira.example.com/PROJECT-123 31 | */ 32 | String trackedBy() default ""; 33 | 34 | /** 35 | * Optional: Probable fix date for this hack i.e. this hack will be cause the build to fail after this date. At such 36 | * time you either need to : 37 | * 1. Fix the issue and remove this annotation 38 | * 2. Update the date to sometime further in the future 39 | * 40 | * Supported date format is: YYYY-MM-DD 41 | * 42 | * @return Probable fix date for this hack 43 | */ 44 | String fixBeforeDate() default ""; 45 | } 46 | -------------------------------------------------------------------------------- /gradlew.bat: -------------------------------------------------------------------------------- 1 | @if "%DEBUG%" == "" @echo off 2 | @rem ########################################################################## 3 | @rem 4 | @rem Gradle startup script for Windows 5 | @rem 6 | @rem ########################################################################## 7 | 8 | @rem Set local scope for the variables with windows NT shell 9 | if "%OS%"=="Windows_NT" setlocal 10 | 11 | set DIRNAME=%~dp0 12 | if "%DIRNAME%" == "" set DIRNAME=. 13 | set APP_BASE_NAME=%~n0 14 | set APP_HOME=%DIRNAME% 15 | 16 | @rem Add default JVM options here. You can also use JAVA_OPTS and GRADLE_OPTS to pass JVM options to this script. 17 | set DEFAULT_JVM_OPTS= 18 | 19 | @rem Find java.exe 20 | if defined JAVA_HOME goto findJavaFromJavaHome 21 | 22 | set JAVA_EXE=java.exe 23 | %JAVA_EXE% -version >NUL 2>&1 24 | if "%ERRORLEVEL%" == "0" goto init 25 | 26 | echo. 27 | echo ERROR: JAVA_HOME is not set and no 'java' command could be found in your PATH. 28 | echo. 29 | echo Please set the JAVA_HOME variable in your environment to match the 30 | echo location of your Java installation. 31 | 32 | goto fail 33 | 34 | :findJavaFromJavaHome 35 | set JAVA_HOME=%JAVA_HOME:"=% 36 | set JAVA_EXE=%JAVA_HOME%/bin/java.exe 37 | 38 | if exist "%JAVA_EXE%" goto init 39 | 40 | echo. 41 | echo ERROR: JAVA_HOME is set to an invalid directory: %JAVA_HOME% 42 | echo. 43 | echo Please set the JAVA_HOME variable in your environment to match the 44 | echo location of your Java installation. 45 | 46 | goto fail 47 | 48 | :init 49 | @rem Get command-line arguments, handling Windows variants 50 | 51 | if not "%OS%" == "Windows_NT" goto win9xME_args 52 | 53 | :win9xME_args 54 | @rem Slurp the command line arguments. 55 | set CMD_LINE_ARGS= 56 | set _SKIP=2 57 | 58 | :win9xME_args_slurp 59 | if "x%~1" == "x" goto execute 60 | 61 | set CMD_LINE_ARGS=%* 62 | 63 | :execute 64 | @rem Setup the command line 65 | 66 | set CLASSPATH=%APP_HOME%\gradle\wrapper\gradle-wrapper.jar 67 | 68 | @rem Execute Gradle 69 | "%JAVA_EXE%" %DEFAULT_JVM_OPTS% %JAVA_OPTS% %GRADLE_OPTS% "-Dorg.gradle.appname=%APP_BASE_NAME%" -classpath "%CLASSPATH%" org.gradle.wrapper.GradleWrapperMain %CMD_LINE_ARGS% 70 | 71 | :end 72 | @rem End local scope for the variables with windows NT shell 73 | if "%ERRORLEVEL%"=="0" goto mainEnd 74 | 75 | :fail 76 | rem Set variable GRADLE_EXIT_CONSOLE if you need the _script_ return code instead of 77 | rem the _cmd.exe /c_ return code! 78 | if not "" == "%GRADLE_EXIT_CONSOLE%" exit 1 79 | exit /b 1 80 | 81 | :mainEnd 82 | if "%OS%"=="Windows_NT" endlocal 83 | 84 | :omega 85 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # record-hacks 2 | `record-hacks` is a Java library that will help you track "creative solutions" in your code. You can use it to document the rationale 3 | behind some questionable choices in your code as well an aspirational date for an intended fix. 4 | 5 | This library provides: 6 | 1. Annotations [`@Hack`](https://github.com/rohitkumbhar/record-hacks/blob/master/annotations/src/main/java/net/kumbhar/dx/Hack.java) and [`@Hacks`](https://github.com/rohitkumbhar/record-hacks/blob/master/annotations/src/main/java/net/kumbhar/dx/Hacks.java) 7 | 1. A compiler processor that will print the hacks in your code as warnings and fail compilation 8 | if a hack is past its `fixByDate` 9 | 10 | These annotations are will be discarded by the compiler after processing and will not be carried over to any class files. 11 | 12 | ## Usage 13 | 14 | ### Import the library 15 | ```xml 16 | 17 | net.kumbhar.dx 18 | record-hacks-annotations 19 | 1.0 20 | 21 | ``` 22 | 23 | ### In your code 24 | ```java 25 | @Hack( 26 | trackedBy = "https://example.com/PROJECT-1234", 27 | fixBeforeDate = "2019-12-31", /* Compilation will fail if this annotation is not removed after this date */ 28 | description = "This is a hack that will make my life miserable soon" 29 | ) 30 | public void hackyMethod() { 31 | // Hack implementation 32 | } 33 | ``` 34 | The annotation can be applied to fields, methods, method parameters, types, local variables and constructors. 35 | 36 | ### Sample output from the [test](https://github.com/rohitkumbhar/record-hacks/blob/master/tests/src/main/java/net/kumbhar/dx/HacksTest.java) 37 | ``` 38 | /workspace/record-hacks/tests/src/main/java/net/kumbhar/dx/HacksTest.java:8: warning: Hack: This should really have the correct type but we dont know what it is. 39 | private Object fieldUsage; 40 | ^ 41 | /workspace/record-hacks/tests/src/main/java/net/kumbhar/dx/HacksTest.java:18: error: Hack: This hack needed to be fixed yesterday 42 | public void buildFailureUsage() { 43 | ^ 44 | /workspace/record-hacks/tests/src/main/java/net/kumbhar/dx/HacksTest.java:22: warning: Hack: This should be its own type 45 | public void methodParameterUsage(@Hack(description = "This should be its own type") Map data) { 46 | ^ 47 | /workspace/record-hacks/tests/src/main/java/net/kumbhar/dx/HacksTest.java:13: warning: Hack: This is a hack that will make my life miserable in 1 month 48 | public void repeatedUsage() { 49 | ^ 50 | /workspace/record-hacks/tests/src/main/java/net/kumbhar/dx/HacksTest.java:13: warning: Hack: This is a hack that will make my life miserable in 2 months 51 | public void repeatedUsage() { 52 | ^ 53 | 1 error 54 | 5 warnings 55 | 56 | ``` 57 | 58 | 59 | 60 | -------------------------------------------------------------------------------- /annotations/src/main/java/net/kumbhar/dx/HackChecker.java: -------------------------------------------------------------------------------- 1 | package net.kumbhar.dx; 2 | 3 | import javax.annotation.processing.AbstractProcessor; 4 | import javax.annotation.processing.RoundEnvironment; 5 | import javax.annotation.processing.SupportedAnnotationTypes; 6 | import javax.annotation.processing.SupportedSourceVersion; 7 | import javax.lang.model.SourceVersion; 8 | import javax.lang.model.element.Element; 9 | import javax.lang.model.element.TypeElement; 10 | import javax.tools.Diagnostic; 11 | import java.text.ParseException; 12 | import java.text.SimpleDateFormat; 13 | import java.util.Date; 14 | import java.util.Set; 15 | 16 | 17 | @SupportedAnnotationTypes({"net.kumbhar.dx.Hack", "net.kumbhar.dx.Hacks"}) 18 | @SupportedSourceVersion(SourceVersion.RELEASE_8) 19 | public class HackChecker extends AbstractProcessor { 20 | 21 | @Override 22 | public boolean process(Set set, RoundEnvironment roundEnvironment) { 23 | 24 | 25 | final Set singular = roundEnvironment.getElementsAnnotatedWith(Hack.class); 26 | for (Element element : singular) { 27 | final Hack hack = element.getAnnotation(Hack.class); 28 | checkHack(hack, element); 29 | } 30 | 31 | final Set plural = roundEnvironment.getElementsAnnotatedWith(Hacks.class); 32 | for (Element element : plural) { 33 | final Hacks hacks = element.getAnnotation(Hacks.class); 34 | for (Hack hack : hacks.value()) { 35 | checkHack(hack, element); 36 | } 37 | } 38 | 39 | 40 | return true; 41 | } 42 | 43 | private void checkHack(Hack hack, Element element) { 44 | 45 | final String description = hack.description(); 46 | final String trackedBy = hack.trackedBy(); 47 | final String fixBeforeDate = hack.fixBeforeDate(); 48 | final boolean expired = expired(fixBeforeDate, element); 49 | final Diagnostic.Kind kind = expired ? Diagnostic.Kind.ERROR : Diagnostic.Kind.MANDATORY_WARNING; 50 | 51 | final StringBuilder messageBuilder = new StringBuilder(); 52 | if (expired) { 53 | messageBuilder.append("Expired Hack: "); 54 | } else { 55 | messageBuilder.append("Hack: "); 56 | } 57 | messageBuilder.append(description); 58 | 59 | if (!trackedBy.trim().equals("")) { 60 | messageBuilder.append(" Tracked by: ").append(trackedBy); 61 | } 62 | 63 | processingEnv.getMessager().printMessage(kind, messageBuilder.toString(), element); 64 | } 65 | 66 | private boolean expired(String fixBeforeDate, Element element) { 67 | 68 | if (fixBeforeDate == null || fixBeforeDate.trim().equals("")) { 69 | return false; 70 | } 71 | 72 | try { 73 | final Date expiryDate = new SimpleDateFormat("yyyy-MM-dd").parse(fixBeforeDate); 74 | return expiryDate.before(new Date()); 75 | } catch (ParseException e) { 76 | processingEnv.getMessager().printMessage(Diagnostic.Kind.ERROR, 77 | "Unable to parse date " + fixBeforeDate + ". Expected format is yyyy-MM-dd", 78 | element); 79 | } 80 | 81 | return false; 82 | } 83 | 84 | } 85 | -------------------------------------------------------------------------------- /gradlew: -------------------------------------------------------------------------------- 1 | #!/usr/bin/env sh 2 | 3 | ############################################################################## 4 | ## 5 | ## Gradle start up script for UN*X 6 | ## 7 | ############################################################################## 8 | 9 | # Attempt to set APP_HOME 10 | # Resolve links: $0 may be a link 11 | PRG="$0" 12 | # Need this for relative symlinks. 13 | while [ -h "$PRG" ] ; do 14 | ls=`ls -ld "$PRG"` 15 | link=`expr "$ls" : '.*-> \(.*\)$'` 16 | if expr "$link" : '/.*' > /dev/null; then 17 | PRG="$link" 18 | else 19 | PRG=`dirname "$PRG"`"/$link" 20 | fi 21 | done 22 | SAVED="`pwd`" 23 | cd "`dirname \"$PRG\"`/" >/dev/null 24 | APP_HOME="`pwd -P`" 25 | cd "$SAVED" >/dev/null 26 | 27 | APP_NAME="Gradle" 28 | APP_BASE_NAME=`basename "$0"` 29 | 30 | # Add default JVM options here. You can also use JAVA_OPTS and GRADLE_OPTS to pass JVM options to this script. 31 | DEFAULT_JVM_OPTS="" 32 | 33 | # Use the maximum available, or set MAX_FD != -1 to use that value. 34 | MAX_FD="maximum" 35 | 36 | warn () { 37 | echo "$*" 38 | } 39 | 40 | die () { 41 | echo 42 | echo "$*" 43 | echo 44 | exit 1 45 | } 46 | 47 | # OS specific support (must be 'true' or 'false'). 48 | cygwin=false 49 | msys=false 50 | darwin=false 51 | nonstop=false 52 | case "`uname`" in 53 | CYGWIN* ) 54 | cygwin=true 55 | ;; 56 | Darwin* ) 57 | darwin=true 58 | ;; 59 | MINGW* ) 60 | msys=true 61 | ;; 62 | NONSTOP* ) 63 | nonstop=true 64 | ;; 65 | esac 66 | 67 | CLASSPATH=$APP_HOME/gradle/wrapper/gradle-wrapper.jar 68 | 69 | # Determine the Java command to use to start the JVM. 70 | if [ -n "$JAVA_HOME" ] ; then 71 | if [ -x "$JAVA_HOME/jre/sh/java" ] ; then 72 | # IBM's JDK on AIX uses strange locations for the executables 73 | JAVACMD="$JAVA_HOME/jre/sh/java" 74 | else 75 | JAVACMD="$JAVA_HOME/bin/java" 76 | fi 77 | if [ ! -x "$JAVACMD" ] ; then 78 | die "ERROR: JAVA_HOME is set to an invalid directory: $JAVA_HOME 79 | 80 | Please set the JAVA_HOME variable in your environment to match the 81 | location of your Java installation." 82 | fi 83 | else 84 | JAVACMD="java" 85 | which java >/dev/null 2>&1 || die "ERROR: JAVA_HOME is not set and no 'java' command could be found in your PATH. 86 | 87 | Please set the JAVA_HOME variable in your environment to match the 88 | location of your Java installation." 89 | fi 90 | 91 | # Increase the maximum file descriptors if we can. 92 | if [ "$cygwin" = "false" -a "$darwin" = "false" -a "$nonstop" = "false" ] ; then 93 | MAX_FD_LIMIT=`ulimit -H -n` 94 | if [ $? -eq 0 ] ; then 95 | if [ "$MAX_FD" = "maximum" -o "$MAX_FD" = "max" ] ; then 96 | MAX_FD="$MAX_FD_LIMIT" 97 | fi 98 | ulimit -n $MAX_FD 99 | if [ $? -ne 0 ] ; then 100 | warn "Could not set maximum file descriptor limit: $MAX_FD" 101 | fi 102 | else 103 | warn "Could not query maximum file descriptor limit: $MAX_FD_LIMIT" 104 | fi 105 | fi 106 | 107 | # For Darwin, add options to specify how the application appears in the dock 108 | if $darwin; then 109 | GRADLE_OPTS="$GRADLE_OPTS \"-Xdock:name=$APP_NAME\" \"-Xdock:icon=$APP_HOME/media/gradle.icns\"" 110 | fi 111 | 112 | # For Cygwin, switch paths to Windows format before running java 113 | if $cygwin ; then 114 | APP_HOME=`cygpath --path --mixed "$APP_HOME"` 115 | CLASSPATH=`cygpath --path --mixed "$CLASSPATH"` 116 | JAVACMD=`cygpath --unix "$JAVACMD"` 117 | 118 | # We build the pattern for arguments to be converted via cygpath 119 | ROOTDIRSRAW=`find -L / -maxdepth 1 -mindepth 1 -type d 2>/dev/null` 120 | SEP="" 121 | for dir in $ROOTDIRSRAW ; do 122 | ROOTDIRS="$ROOTDIRS$SEP$dir" 123 | SEP="|" 124 | done 125 | OURCYGPATTERN="(^($ROOTDIRS))" 126 | # Add a user-defined pattern to the cygpath arguments 127 | if [ "$GRADLE_CYGPATTERN" != "" ] ; then 128 | OURCYGPATTERN="$OURCYGPATTERN|($GRADLE_CYGPATTERN)" 129 | fi 130 | # Now convert the arguments - kludge to limit ourselves to /bin/sh 131 | i=0 132 | for arg in "$@" ; do 133 | CHECK=`echo "$arg"|egrep -c "$OURCYGPATTERN" -` 134 | CHECK2=`echo "$arg"|egrep -c "^-"` ### Determine if an option 135 | 136 | if [ $CHECK -ne 0 ] && [ $CHECK2 -eq 0 ] ; then ### Added a condition 137 | eval `echo args$i`=`cygpath --path --ignore --mixed "$arg"` 138 | else 139 | eval `echo args$i`="\"$arg\"" 140 | fi 141 | i=$((i+1)) 142 | done 143 | case $i in 144 | (0) set -- ;; 145 | (1) set -- "$args0" ;; 146 | (2) set -- "$args0" "$args1" ;; 147 | (3) set -- "$args0" "$args1" "$args2" ;; 148 | (4) set -- "$args0" "$args1" "$args2" "$args3" ;; 149 | (5) set -- "$args0" "$args1" "$args2" "$args3" "$args4" ;; 150 | (6) set -- "$args0" "$args1" "$args2" "$args3" "$args4" "$args5" ;; 151 | (7) set -- "$args0" "$args1" "$args2" "$args3" "$args4" "$args5" "$args6" ;; 152 | (8) set -- "$args0" "$args1" "$args2" "$args3" "$args4" "$args5" "$args6" "$args7" ;; 153 | (9) set -- "$args0" "$args1" "$args2" "$args3" "$args4" "$args5" "$args6" "$args7" "$args8" ;; 154 | esac 155 | fi 156 | 157 | # Escape application args 158 | save () { 159 | for i do printf %s\\n "$i" | sed "s/'/'\\\\''/g;1s/^/'/;\$s/\$/' \\\\/" ; done 160 | echo " " 161 | } 162 | APP_ARGS=$(save "$@") 163 | 164 | # Collect all arguments for the java command, following the shell quoting and substitution rules 165 | eval set -- $DEFAULT_JVM_OPTS $JAVA_OPTS $GRADLE_OPTS "\"-Dorg.gradle.appname=$APP_BASE_NAME\"" -classpath "\"$CLASSPATH\"" org.gradle.wrapper.GradleWrapperMain "$APP_ARGS" 166 | 167 | # by default we should be in the correct project dir, but when run from Finder on Mac, the cwd is wrong 168 | if [ "$(uname)" = "Darwin" ] && [ "$HOME" = "$PWD" ]; then 169 | cd "$(dirname "$0")" 170 | fi 171 | 172 | exec "$JAVACMD" "$@" 173 | --------------------------------------------------------------------------------