Add support for customMetas and customDefines fields (#573)

* Add support for customMetas and customDefines fields

* Move new documentation fields to 'documentation' object

Also guard against previous haxe versions

* Add metadata/define source

* Update json schema

* Check documentation fields

* Rebuild run.n

* Let maintainers add more documentation resources if they want

* Revert "Let maintainers add more documentation resources if they want"

This reverts commit cb7976c.

* Typo

* Rename Compiler metadata/defines functions

* Rebuild run.n

schema.json

@@ -47,6 +47,21 @@
 			},
 			"additionalProperties": false
 		},
+		"documentation": {
+			"type": "object",
+			"description": "Project's documentation resources",
+			"properties": {
+				"defines": {
+					"type": "string",
+					"description": "Relative path to json file describing this project's custom defines"
+				},
+				"metadata": {
+					"type": "string",
+					"description": "Relative path to json file describing this project's custom metadata"
+				}
+			},
+			"additionalProperties": false
+		},
 		"releasenote": {
 			"description": "Short description of changes made in this version",
 			"type": "string"

src/haxelib/Data.hx

@@ -152,7 +152,35 @@ typedef Infos = {
 	var contributors : Array<String>;
 	@:optional var tags : Array<String>;
 	@:optional var dependencies : Dependencies;
-	@:optional var main:String;
+	@:optional var main : String;
+	@:optional var documentation : LibraryDocumentation;
+}
+
+/** Documentation data held in the `documentation` field of the `haxelib.json` file. **/
+typedef LibraryDocumentation = {
+	@:optional var defines : String;
+	@:optional var metadata : String;
+}
+
+/** Metadata documentation data as should be declared in the json linked in the
+ * `documentation.metadata` field of the `haxelib.json` file. **/
+typedef MetadataDocumentation = {
+	var metadata : String;
+	var doc : String;
+	@:optional var platforms : Array<String>;
+	@:optional var params : Array<String>;
+	@:optional var targets : Array<String>;
+	@:optional var links : Array<String>;
+}
+
+/** Define documentation data as should be declared in the json linked in the
+ * `documentation.defines` field of the `haxelib.json` file. **/
+typedef DefineDocumentation = {
+	var define : String;
+	var doc : String;
+	@:optional var platforms : Array<String>;
+	@:optional var params : Array<String>;
+	@:optional var links : Array<String>;
 }
 
 /** An abstract enum representing the different Licenses a project can have. **/
@@ -263,6 +291,48 @@ class Data {
 		}
 	}
 
+	/** Throws an exception if files referenced in `documentation` field of an `infos` do not exist or are invalid **/
+	public static function checkDocumentation( zip : List<Entry>, infos : Infos ) {
+		if (infos.documentation == null) return;
+
+		var hasDefines = infos.documentation.defines == null;
+		var hasMetadata = infos.documentation.metadata == null;
+		if (!hasDefines && !hasMetadata) return;
+
+		var basePath = Data.locateBasePath(zip);
+		var definesPath = hasDefines ? null : basePath + infos.documentation.defines;
+		var metadataPath = hasMetadata ? null : basePath + infos.documentation.metadata;
+		var definesFound = false;
+		var metadataFound = false;
+
+		for (f in zip) {
+			if (hasDefines && StringTools.startsWith(f.fileName, definesPath)) {
+				definesFound = true;
+				try {
+					var jsondata = Reader.unzip(f).toString();
+					var defines:Array<DefineDocumentation> = Json.parse(jsondata);
+					Validator.validate(defines);
+				} catch (_:Dynamic) {
+					throw 'Defines documentation json file does not match expected format';
+				}
+			} else if (hasMetadata && StringTools.startsWith(f.fileName, metadataPath)) {
+				metadataFound = true;
+				try {
+					var jsondata = Reader.unzip(f).toString();
+					var metas:Array<MetadataDocumentation> = Json.parse(jsondata);
+					Validator.validate(metas);
+				} catch (_:Dynamic) {
+					throw 'Metadata documentation json file does not match expected format';
+				}
+			}
+
+			if ((!hasDefines || definesFound) && (!hasMetadata || metadataFound)) break;
+		}
+
+		if (hasDefines && !definesFound) throw 'Json file `${infos.documentation.defines}` not found';
+		if (hasMetadata && !metadataFound) throw 'Json file `${infos.documentation.metadata}` not found';
+	}
+
 	static function cleanDependencies(dependencies:Null<Dependencies>):Void {
 		if (dependencies == null)
 			return;

src/haxelib/api/Connection.hx

@@ -402,6 +402,7 @@ class Connection {
 
 		final infos = Data.readDataFromZip(zip, CheckData);
 		Data.checkClassPath(zip, infos);
+		Data.checkDocumentation(zip, infos);
 
 		// ask user which contributor they are
 		final user = login(infos.contributors);

src/haxelib/api/GlobalScope.hx

@@ -185,6 +185,25 @@ class GlobalScope extends Scope {
 			);
 			addLine('-D ${info.name}=${info.version}');
 
+			if (info.documentation != null) {
+				var doc = info.documentation;
+
+				// we'll have to change this to "4.3.0" after the release
+				if (resolveCompiler().version >= SemVer.ofString("4.3.0-rc.1")) {
+					// custom defines if defined
+					if (doc.defines != null && doc.defines != "") {
+						var path = Path.join([resolved.path, doc.defines]);
+						addLine('--macro registerDefinesDescriptionFile(\'$path\', \'${info.name}\')');
+					}
+
+					// custom metadatas if defined
+					if (doc.metadata != null && doc.metadata != "") {
+						var path = Path.join([resolved.path, doc.metadata]);
+						addLine('--macro registerMetadataDescriptionFile(\'$path\', \'${info.name}\')');
+					}
+				}
+			}
+
 			// add dependencies to stack
 			final dependencies = info.dependencies.extractDataArray();
 

test/libraries/libBadDefineJson/doc/defines.json

@@ -0,0 +1,5 @@
+[
+	{
+		"name": "Malformed define"
+	}
+]

test/libraries/libBadDefineJson/haxelib.json

@@ -0,0 +1,13 @@
+{
+	"name": "BadDefineJson",
+	"url" : "http://example.org",
+	"license": "GPL",
+	"tags": ["bar", "test"],
+	"description": "This project is an example of an haxelib project",
+	"version": "1.0.0",
+	"releasenote": "Initial release, everything is working correctly",
+	"documentation": {
+		"defines": "doc/defines.json"
+	},
+	"contributors": ["Bar"]
+}

test/libraries/libBadMetaJson/doc/meta.json

@@ -0,0 +1 @@
+This is not a json file

test/libraries/libBadMetaJson/haxelib.json

@@ -0,0 +1,13 @@
+{
+	"name": "BadMetaJson",
+	"url" : "http://example.org",
+	"license": "GPL",
+	"tags": ["bar", "test"],
+	"description": "This project is an example of an haxelib project",
+	"version": "1.0.0",
+	"releasenote": "Initial release, everything is working correctly",
+	"documentation": {
+		"metadata": "doc/meta.json"
+	},
+	"contributors": ["Bar"]
+}

test/libraries/libBadMetaJson2/doc/meta.json

@@ -0,0 +1,5 @@
+[
+	{
+		"name": "Malformed meta"
+	}
+]

test/libraries/libBadMetaJson2/haxelib.json

@@ -0,0 +1,13 @@
+{
+	"name": "BadMetaJson2",
+	"url" : "http://example.org",
+	"license": "GPL",
+	"tags": ["bar", "test"],
+	"description": "This project is an example of an haxelib project",
+	"version": "1.0.0",
+	"releasenote": "Initial release, everything is working correctly",
+	"documentation": {
+		"metadata": "doc/meta.json"
+	},
+	"contributors": ["Bar"]
+}

test/libraries/libDocumentationFiles/doc/defines.json

@@ -0,0 +1,13 @@
+[
+	{
+		"define": "test",
+		"doc": "Test define"
+	},
+	{
+		"define": "test2",
+		"doc": "Test define 2",
+		"platforms": ["eval"],
+		"params": ["foo"],
+		"links": ["https://example.com"]
+	}
+]

test/libraries/libDocumentationFiles/doc/meta.json

@@ -0,0 +1,14 @@
+[
+	{
+		"metadata": ":test",
+		"doc": "Some test metadata"
+	},
+	{
+		"metadata": ":test2",
+		"doc": "Some other test metadata",
+		"platforms": ["eval"],
+		"params": ["foo"],
+		"links": ["https://example.com"],
+		"targets": ["TClass", "TClassField"]
+	}
+]

test/libraries/libDocumentationFiles/haxelib.json

@@ -0,0 +1,14 @@
+{
+	"name": "DocumentationFiles",
+	"url" : "http://example.org",
+	"license": "GPL",
+	"tags": ["bar", "test"],
+	"description": "This project is an example of an haxelib project",
+	"version": "1.0.0",
+	"releasenote": "Initial release, everything is working correctly",
+	"documentation": {
+		"metadata": "doc/meta.json",
+		"defines": "doc/defines.json"
+	},
+	"contributors": ["Bar"]
+}

test/libraries/libMissingMetaJson/haxelib.json

@@ -0,0 +1,13 @@
+{
+	"name": "MissingMetaJson",
+	"url" : "http://example.org",
+	"license": "GPL",
+	"tags": ["bar", "test"],
+	"description": "This project is an example of an haxelib project",
+	"version": "1.0.0",
+	"releasenote": "Initial release, everything is working correctly",
+	"documentation": {
+		"metadata": "doc/meta.json"
+	},
+	"contributors": ["Bar"]
+}

test/tests/TestData.hx

@@ -104,6 +104,27 @@ class TestData extends TestBase {
 		assertEquals( ok, true );
 	}
 
+	public function testCheckDocumentation() {
+		var results = [
+			"DocumentationFiles" => true,
+			"BadMetaJson" => false,
+			"BadMetaJson2" => false,
+			"BadDefineJson" => false
+		];
+
+		for (r in results.keys()) {
+			var zip = Reader.readZip(new BytesInput(File.getBytes('test/libraries/lib$r.zip')));
+			var info = Data.readDataFromZip(zip, CheckData);
+
+			try {
+				Data.checkDocumentation(zip,info);
+				assertTrue(results.get(r));
+			} catch (e:Dynamic) {
+				assertFalse(results.get(r));
+			}
+		}
+	}
+
 	public function testReadDataWithDataCheck() {
 		assertFalse( readDataOkay("bad json") );