added untracked parsing attempts files
[jalview.git] / utils / MessageBundleChecker.java
1
2 /*
3  * Jalview - A Sequence Alignment Editor and Viewer ($$Version-Rel$$)
4  * Copyright (C) $$Year-Rel$$ The Jalview Authors
5  * 
6  * This file is part of Jalview.
7  * 
8  * Jalview is free software: you can redistribute it and/or
9  * modify it under the terms of the GNU General Public License 
10  * as published by the Free Software Foundation, either version 3
11  * of the License, or (at your option) any later version.
12  *  
13  * Jalview is distributed in the hope that it will be useful, but 
14  * WITHOUT ANY WARRANTY; without even the implied warranty 
15  * of MERCHANTABILITY or FITNESS FOR A PARTICULAR 
16  * PURPOSE.  See the GNU General Public License for more details.
17  * 
18  * You should have received a copy of the GNU General Public License
19  * along with Jalview.  If not, see <http://www.gnu.org/licenses/>.
20  * The Jalview Authors are detailed in the 'AUTHORS' file.
21  */
22 import java.io.BufferedReader;
23 import java.io.File;
24 import java.io.FileReader;
25 import java.io.IOException;
26 import java.util.HashSet;
27 import java.util.Iterator;
28 import java.util.Properties;
29 import java.util.Set;
30 import java.util.TreeSet;
31 import java.util.regex.Pattern;
32
33 /**
34  * This class scans Java source files for calls to MessageManager and reports
35  * <ul>
36  * <li>calls using keys not found in Messages.properties</li>
37  * <li>any unused keys in Messages.properties</li>
38  * </ul>
39  * It does not handle dynamically constructed keys, these are reported as
40  * possible errors for manual inspection. <br>
41  * For comparing translated bundles with Messages.properties, see i18nAnt.xml
42  * 
43  * @author gmcarstairs
44  *
45  */
46 public class MessageBundleChecker implements BufferedLineReader.LineCleaner
47 {
48   /*
49    * regex ^"[^"]*"$
50    * opening quote, closing quote, no quotes in between
51    */
52   static Pattern STRING_PATTERN = Pattern.compile("^\"[^\"]*\"$");
53
54   /*
55    * number of text lines to read at a time in order to parse
56    * code that is split over several lines
57    */
58   static int bufferSize = 3;
59
60   /*
61    * resource bundle key is arg0 for these methods
62    */
63   static final String METHOD1 = "MessageManager.getString(";
64
65   static final String METHOD2 = "MessageManager.formatMessage(";
66
67   static final String METHOD3 = "MessageManager.getStringOrReturn(";
68
69   /*
70    * resource bundle key is arg1 for this method
71    */
72   static final String JVINIT = "JvSwingUtils.jvInitComponent(";
73
74   static final String[] METHODS = { METHOD1, METHOD2, METHOD3, JVINIT };
75
76   /*
77    * root of the Java source folders we want to scan
78    */
79   String sourcePath;
80
81   /*
82    * contents of Messages.properties
83    */
84   private Properties messages;
85
86   /*
87    * keys from Messages.properties
88    * we remove entries from here as they are found to be used
89    * any left over are unused entries
90    */
91   private TreeSet<String> messageKeys;
92
93   private int javaCount;
94
95   private Set<String> invalidKeys;
96
97   private Set<String> dynamicKeys;
98
99   /**
100    * Runs the scan given the path to the root of Java source directories
101    * 
102    * @param args
103    *          [0] path to the source folder to scan
104    * @param args
105    *          [1] (optional) read buffer size (default is 3); increasing this
106    *          may detect more results but will give higher error counts due to
107    *          double counting of the same code
108    * @throws IOException
109    */
110   public static void main(String[] args) throws IOException
111   {
112     if (args.length != 1 && args.length != 2)
113     {
114       System.out.println("Usage: <pathToSourceFolder> [readBufferSize]");
115       return;
116     }
117     if (args.length == 2)
118     {
119       bufferSize = Integer.valueOf(args[1]);
120     }
121     new MessageBundleChecker().doMain(args[0]);
122   }
123
124   /**
125    * Main method to perform the work
126    * 
127    * @param srcPath
128    * @throws IOException
129    */
130   private void doMain(String srcPath) throws IOException
131   {
132     System.out.println(
133             "Scanning " + srcPath + " for calls to MessageManager\n");
134
135     sourcePath = srcPath;
136     loadMessages();
137     File dir = new File(srcPath);
138     if (!dir.exists())
139     {
140       System.out.println(srcPath + " not found");
141       return;
142     }
143
144     invalidKeys = new HashSet<>();
145     dynamicKeys = new HashSet<>();
146
147     if (dir.isDirectory())
148     {
149       scanDirectory(dir);
150     }
151     else
152     {
153       scanFile(dir);
154     }
155     reportResults();
156   }
157
158   /**
159    * Prints out counts to sysout
160    */
161   private void reportResults()
162   {
163     System.out.println(
164             "\nMessages.properties has " + messages.size() + " keys");
165     System.out.println("Scanned " + javaCount + " source files\n");
166
167     if (!invalidKeys.isEmpty())
168     {
169       System.out.println("Found " + invalidKeys.size()
170               + " possibly invalid unmatched key(s) in source code"
171               + (invalidKeys.size() > 1 ? "s" : ""));
172     }
173
174     System.out.println(
175             "Keys not found in source code, assumed constructed dynamically:");
176     int dynamicCount = 0;
177     for (String key : messageKeys)
178     {
179       if (isDynamic(key))
180       {
181         System.out.println("    " + key);
182         dynamicCount++;
183       }
184     }
185
186     if (dynamicCount < messageKeys.size())
187     {
188       System.out.println((messageKeys.size() - dynamicCount)
189               + " key(s) not found, possibly unused, or used indirectly (check code manually!)");
190       for (String key : messageKeys)
191       {
192         if (!isDynamic(key))
193         {
194           System.out.println("    " + key);
195         }
196       }
197     }
198     System.out
199             .println("\nRun i18nAnt.xml to compare other message bundles");
200   }
201
202   /**
203    * Answers true if the key starts with one of the recorded dynamic key stubs,
204    * else false
205    * 
206    * @param key
207    * @return
208    */
209   private boolean isDynamic(String key)
210   {
211     for (String dynamic : dynamicKeys)
212     {
213       if (key.startsWith(dynamic))
214       {
215         return true;
216       }
217     }
218     return false;
219   }
220
221   /**
222    * Scan all files within a directory
223    * 
224    * @param dir
225    * @throws IOException
226    */
227   private void scanDirectory(File dir) throws IOException
228   {
229     File[] files = dir.listFiles();
230     if (files != null)
231     {
232       for (File f : files)
233       {
234         if (f.isDirectory())
235         {
236           scanDirectory(f);
237         }
238         else
239         {
240           scanFile(f);
241         }
242       }
243     }
244   }
245
246   /**
247    * Scan a Java file
248    * 
249    * @param f
250    */
251   private void scanFile(File f) throws IOException
252   {
253     String path = f.getPath();
254     if (!path.endsWith(".java"))
255     {
256       return;
257     }
258     javaCount++;
259
260     /*
261      * skip class with designed dynamic lookup call
262      */
263     if (path.endsWith("gui/JvSwingUtils.java"))
264     {
265       return;
266     }
267
268     BufferedReader br = new BufferedReader(new FileReader(f));
269     BufferedLineReader blr = new BufferedLineReader(br, bufferSize, this);
270
271     int lineNo = 0;
272     String line = blr.read();
273     while (line != null)
274     {
275       lineNo++;
276       inspectSourceLines(path, lineNo, line);
277       line = blr.read();
278     }
279     br.close();
280
281   }
282
283   /**
284    * Look for calls to MessageManager methods, possibly split over two or more
285    * lines that have been concatenated while parsing the file
286    * 
287    * @param path
288    * @param lineNo
289    * @param line
290    */
291   private void inspectSourceLines(String path, int lineNo,
292           final String line)
293   {
294     String lineNos = String.format("%d-%d", lineNo,
295             lineNo + bufferSize - 1);
296     for (String method : METHODS)
297     {
298       int pos = line.indexOf(method);
299       if (pos == -1)
300       {
301         continue;
302       }
303
304       /*
305        * extract what follows the opening bracket of the method call
306        */
307       String methodArgs = line.substring(pos + method.length()).trim();
308       if ("".equals(methodArgs))
309       {
310         /*
311          * arguments are on next line - catch in the next read loop iteration
312          */
313         continue;
314       }
315       if (methodArgs.indexOf(",") == -1 && methodArgs.indexOf(")") == -1)
316       {
317         /*
318          * arguments continue on next line - catch in the next read loop iteration
319          */
320         continue;
321       }
322
323       if (JVINIT == method && methodArgs.indexOf(",") == -1)
324       {
325         /*
326          * not interested in 1-arg calls to jvInitComponent
327          */
328         continue;
329       }
330
331       String messageKey = getMessageKey(method, methodArgs);
332
333       if (METHOD3 == method)
334       {
335         String key = messageKey.substring(1, messageKey.length() - 1);
336         if (!dynamicKeys.contains(key))
337         {
338 //          System.out.println(String.format(
339 //                  "Dynamic key \"" + key + "\" at %s line %s %s",
340 //                  path.substring(sourcePath.length()), lineNos, line));
341           dynamicKeys.add(key);
342         }
343         continue;
344       }
345
346       if (messageKey == null)
347       {
348         System.out.println(String.format("Trouble parsing %s line %s %s",
349                 path.substring(sourcePath.length()), lineNos, line));
350         continue;
351       }
352
353       if (!(STRING_PATTERN.matcher(messageKey).matches()))
354       {
355 //        System.out.println(String.format("Dynamic key at %s line %s %s",
356 //                path.substring(sourcePath.length()), lineNos, line));
357         continue;
358       }
359
360       /*
361        * strip leading and trailing quote
362        */
363       messageKey = messageKey.substring(1, messageKey.length() - 1);
364
365       if (!this.messages.containsKey(messageKey))
366       {
367         if (!invalidKeys.contains(messageKey))
368         {
369           // report each key the first time found only
370           System.out.println(String.format(
371                   "Unmatched key '%s' at line %s of %s", messageKey,
372                   lineNos, path.substring(sourcePath.length())));
373           invalidKeys.add(messageKey);
374         }
375       }
376       messageKeys.remove(messageKey);
377     }
378
379     /*
380      * and a brute force scan for _any_ as yet unseen message key, to catch the
381      * cases where it is in a variable or a condition
382      */
383     if (line.contains("\""))
384     {
385       Iterator<String> it = messageKeys.iterator();
386       while (it.hasNext())
387       {
388         if (line.contains(it.next()))
389         {
390           it.remove(); // remove as 'seen'
391         }
392       }
393     }
394   }
395
396   /**
397    * Helper method to parse out the resource bundle key parameter of a method
398    * call
399    * 
400    * @param method
401    * @param methodArgs
402    *          the rest of the source line starting with arguments to method
403    * @return
404    */
405   private String getMessageKey(String method, String methodArgs)
406   {
407     String key = methodArgs;
408
409     /*
410      * locate second argument if calling jvInitComponent()
411      */
412     if (method == JVINIT)
413     {
414       int commaLoc = methodArgs.indexOf(",");
415       if (commaLoc == -1)
416       {
417         return null;
418       }
419       key = key.substring(commaLoc + 1).trim();
420     }
421
422     /*
423      * take up to next comma or ) or end of line
424      */
425     int commaPos = key.indexOf(",");
426     int bracePos = key.indexOf(")");
427     int endPos = commaPos == -1 ? bracePos
428             : (bracePos == -1 ? commaPos : Math.min(commaPos, bracePos));
429     if (endPos == -1 && key.length() > 1 && key.endsWith("\""))
430     {
431       endPos = key.length();
432     }
433
434     return endPos == -1 ? null : key.substring(0, endPos);
435   }
436
437   /**
438    * Loads properties from Message.properties
439    * 
440    * @throws IOException
441    */
442   void loadMessages() throws IOException
443   {
444     messages = new Properties();
445     FileReader reader = new FileReader(
446             new File(sourcePath, "../resources/lang/Messages.properties"));
447     messages.load(reader);
448     reader.close();
449
450     messageKeys = new TreeSet<>();
451     for (Object key : messages.keySet())
452     {
453       messageKeys.add((String) key);
454     }
455
456   }
457
458   /**
459    * Remove any trailing comments, change tabs to space, and trim
460    */
461   @Override
462   public String cleanLine(String l)
463   {
464     if (l != null)
465     {
466       int pos = l.indexOf("//");
467       if (pos != -1)
468       {
469         l = l.substring(0, pos);
470       }
471       l = l.replace("\t", " ").trim();
472     }
473     return l;
474   }
475
476 }