Merge pull request #25 from wikimedia/optout

Allow individual checks to be disabled in config
wikimedia · Aug 25, 2015 · 21619cc · 21619cc
2 parents ed93f3b + f487f68
commit 21619cc
Show file tree

Hide file tree

Showing 17 changed files with 168 additions and 36 deletions.
diff --git a/Gruntfile.js b/Gruntfile.js
@@ -34,6 +34,30 @@ module.exports = function ( grunt ) {
 					sourceFile: 'messages.json',
 					documentationFile: 'documentation.json'
 				}
+			},
+			requireMetadata: {
+				src: 'test/requireMetadata',
+				options: {
+					requireMetadata: false
+				}
+			},
+			requireCompleteMessageDocumentation: {
+				src: 'test/requireCompleteMessageDocumentation',
+				options: {
+					requireCompleteMessageDocumentation: false
+				}
+			},
+			requireNonEmptyDocumentation: {
+				src: 'test/requireNonEmptyDocumentation',
+				options: {
+					requireNonEmptyDocumentation: false
+				}
+			},
+			requireNoUnusedDocumentation: {
+				src: 'test/requireNoUnusedDocumentation',
+				options: {
+					requireNoUnusedDocumentation: false
+				}
 			}
 		},
 		watch: {

diff --git a/README.md b/README.md
@@ -46,6 +46,30 @@ Default value: `"qqq.json"`
 
 The JSON file providing the documentation messages.
 
+### requireMetadata
+Type: `boolean`
+Default value: `true`
+
+Whether to fail if message files don't have a `@metadata` meta-data key.
+
+### requireCompleteMessageDocumentation
+Type: `boolean`
+Default value: `true`
+
+Whether to fail if any message is in the primary file but not documented.
+
+### requireNonEmptyDocumentation
+Type: `boolean`
+Default value: `true`
+
+Whether to fail if any message is in the primary file but documented as a blank string.
+
+### requireNoUnusedDocumentation
+Type: `boolean`
+Default value: `true`
+
+Whether to fail if any documented message isn't in the primary file.
+
 
 Example uses
 --------------------

diff --git a/tasks/banana.js b/tasks/banana.js
@@ -9,7 +9,10 @@ module.exports = function ( grunt ) {
 			path = require( 'path' ),
 			options = this.options( {
 				sourceFile: 'en.json',
-				documentationFile: 'qqq.json'
+				documentationFile: 'qqq.json',
+				requireMetadata: true,
+				requireCompleteMessageDocumentation: true,
+				requireNoUnusedDocumentation: true
 			} ),
 			messageCount = 0;
 
@@ -20,6 +23,12 @@ module.exports = function ( grunt ) {
 
 		ok = true;
 
+		if ( this.filesSrc.length === 0 ) {
+			grunt.log.error( 'Target directory does not exist.' );
+			ok = false;
+			return;
+		}
+
 		this.filesSrc.forEach( function ( dir ) {
 			var sourceMessages, sourceMessageKeys,
 				documentationMessages, documentationMessageKeys,
@@ -49,7 +58,7 @@ module.exports = function ( grunt ) {
 			}
 
 			sourceMessagesMetadataIndex = sourceMessageKeys.indexOf( '@metadata' );
-			if ( sourceMessagesMetadataIndex === -1 ) {
+			if ( options.requireMetadata && sourceMessagesMetadataIndex === -1 ) {
 				grunt.log.error( 'Source file lacks a metadata block.' );
 				ok = false;
 				return;
@@ -59,7 +68,7 @@ module.exports = function ( grunt ) {
 			messageCount += sourceMessageKeys.length;
 
 			documentationMessagesMetadataIndex = documentationMessageKeys.indexOf( '@metadata' );
-			if ( documentationMessagesMetadataIndex === -1 ) {
+			if ( options.requireMetadata && documentationMessagesMetadataIndex === -1 ) {
 				grunt.log.error( 'Documentation file lacks a metadata block.' );
 				ok = false;
 				return;
@@ -83,43 +92,49 @@ module.exports = function ( grunt ) {
 				sourceMessageKeys.splice( 0, 1 );
 			}
 
-			count = sourceMessageMissing.length;
-			if ( count > 0 ) {
-				ok = false;
+			if ( options.requireCompleteMessageDocumentation ) {
+				count = sourceMessageMissing.length;
+				if ( count > 0 ) {
+					ok = false;
 
-				grunt.log.error(
-					count + ' message' + ( count > 1 ? 's lack' : ' lacks' ) + ' documentation.'
-				);
+					grunt.log.error(
+						count + ' message' + ( count > 1 ? 's lack' : ' lacks' ) + ' documentation.'
+					);
 
-				sourceMessageMissing.forEach( function ( message ) {
-					grunt.log.error( 'Message "' + message + '" lacks documentation.' );
-				} );
+					sourceMessageMissing.forEach( function ( message ) {
+						grunt.log.error( 'Message "' + message + '" lacks documentation.' );
+					} );
+				}
 			}
 
-			count = documentationMessageBlanks.length;
-			if ( count > 0 ) {
-				ok = false;
+			if ( options.requireNonEmptyDocumentation ) {
+				count = documentationMessageBlanks.length;
+				if ( count > 0 ) {
+					ok = false;
 
-				grunt.log.error(
-					count + ' documented message' + ( count > 1 ? 's are' : ' is' ) + ' blank.'
-				);
+					grunt.log.error(
+						count + ' documented message' + ( count > 1 ? 's are' : ' is' ) + ' blank.'
+					);
 
-				documentationMessageBlanks.forEach( function ( message ) {
-					grunt.log.error( 'Message "' + message + '" is documented with a blank string.' );
-				} );
+					documentationMessageBlanks.forEach( function ( message ) {
+						grunt.log.error( 'Message "' + message + '" is documented with a blank string.' );
+					} );
+				}
 			}
 
-			count = documentationMessageKeys.length;
-			if ( count > 0 ) {
-				ok = false;
+			if ( options.requireNoUnusedDocumentation ) {
+				count = documentationMessageKeys.length;
+				if ( count > 0 ) {
+					ok = false;
 
-				grunt.log.error(
-					count + ' documented message' + ( count > 1 ? 's are' : ' is' ) + ' undefined.'
-				);
+					grunt.log.error(
+						count + ' documented message' + ( count > 1 ? 's are' : ' is' ) + ' undefined.'
+					);
 
-				documentationMessageKeys.forEach( function ( message ) {
-					grunt.log.error( 'Message "' + message + '" is documented but undefined.' );
-				} );
+					documentationMessageKeys.forEach( function ( message ) {
+						grunt.log.error( 'Message "' + message + '" is documented but undefined.' );
+					} );
+				}
 			}
 		} );
 

diff --git a/test/advanced/a/documentation.json b/test/advanced/a/documentation.json
@@ -7,4 +7,4 @@
 	"second-message-key": "second message definition",
 	"third-message-key": "third message definition",
 	"four-message-key": "four message definition"
-}
+}
diff --git a/test/advanced/a/messages.json b/test/advanced/a/messages.json
@@ -6,4 +6,4 @@
 	"second-message-key": "second message value",
 	"third-message-key": "third message value",
 	"four-message-key": "four message value"
-}
+}
diff --git a/test/advanced/b/documentation.json b/test/advanced/b/documentation.json
@@ -7,4 +7,4 @@
 	"second-message-key": "second message definition",
 	"third-message-key": "third message definition",
 	"four-message-key": "four message definition"
-}
+}
diff --git a/test/advanced/b/messages.json b/test/advanced/b/messages.json
@@ -6,4 +6,4 @@
 	"second-message-key": "second message value",
 	"third-message-key": "third message value",
 	"four-message-key": "four message value"
-}
+}
diff --git a/test/requireCompleteMessageDocumentation/en.json b/test/requireCompleteMessageDocumentation/en.json
@@ -0,0 +1,9 @@
+{
+	"@metadata": {
+		"metadata-key": "metadata value"
+	},
+	"first-message-key": "first message value",
+	"second-message-key": "second message value",
+	"third-message-key": "third message value",
+	"four-message-key": "four message value"
+}
diff --git a/test/requireCompleteMessageDocumentation/qqq.json b/test/requireCompleteMessageDocumentation/qqq.json
@@ -0,0 +1,9 @@
+{
+	"@metadata": {
+		"first-metadata-key": "metadata value",
+		"second-metadata-key": "metadata value"
+	},
+	"first-message-key": "first message definition",
+	"second-message-key": "second message definition",
+	"four-message-key": "four message definition"
+}
diff --git a/test/requireMetadata/en.json b/test/requireMetadata/en.json
@@ -0,0 +1,6 @@
+{
+	"first-message-key": "first message value",
+	"second-message-key": "second message value",
+	"third-message-key": "third message value",
+	"four-message-key": "four message value"
+}
diff --git a/test/requireMetadata/qqq.json b/test/requireMetadata/qqq.json
@@ -0,0 +1,6 @@
+{
+	"first-message-key": "first message definition",
+	"second-message-key": "second message definition",
+	"third-message-key": "third message definition",
+	"four-message-key": "four message definition"
+}
diff --git a/test/requireNoUnusedDocumentation/en.json b/test/requireNoUnusedDocumentation/en.json
@@ -0,0 +1,9 @@
+{
+	"@metadata": {
+		"metadata-key": "metadata value"
+	},
+	"first-message-key": "first message value",
+	"second-message-key": "second message value",
+	"third-message-key": "third message value",
+	"four-message-key": "four message value"
+}
diff --git a/test/requireNoUnusedDocumentation/qqq.json b/test/requireNoUnusedDocumentation/qqq.json
@@ -0,0 +1,11 @@
+{
+	"@metadata": {
+		"first-metadata-key": "metadata value",
+		"second-metadata-key": "metadata value"
+	},
+	"first-message-key": "first message definition",
+	"second-message-key": "second message definition",
+	"third-message-key": "third message definition",
+	"four-message-key": "four message definition",
+	"five-message-key": "extra message definition"
+}
diff --git a/test/requireNonEmptyDocumentation/en.json b/test/requireNonEmptyDocumentation/en.json
@@ -0,0 +1,9 @@
+{
+	"@metadata": {
+		"metadata-key": "metadata value"
+	},
+	"first-message-key": "first message value",
+	"second-message-key": "second message value",
+	"third-message-key": "third message value",
+	"four-message-key": "four message value"
+}
diff --git a/test/requireNonEmptyDocumentation/qqq.json b/test/requireNonEmptyDocumentation/qqq.json
@@ -0,0 +1,10 @@
+{
+	"@metadata": {
+		"first-metadata-key": "metadata value",
+		"second-metadata-key": "metadata value"
+	},
+	"first-message-key": "first message definition",
+	"second-message-key": "",
+	"third-message-key": "third message definition",
+	"four-message-key": "four message definition"
+}
diff --git a/test/simple/en.json b/test/simple/en.json
@@ -6,4 +6,4 @@
 	"second-message-key": "second message value",
 	"third-message-key": "third message value",
 	"four-message-key": "four message value"
-}
+}
diff --git a/test/simple/qqq.json b/test/simple/qqq.json
@@ -7,4 +7,4 @@
 	"second-message-key": "second message definition",
 	"third-message-key": "third message definition",
 	"four-message-key": "four message definition"
-}
+}