Merge pull request #71 from jhm-ciberman/general-refactor

WIP: Big update: v4.0.0

package.json

@@ -45,6 +45,7 @@
   },
   "devDependencies": {
     "@types/fs-extra": "^8.0.0",
+    "@types/jsonschema": "^1.1.1",
     "@types/minimatch": "^3.0.3",
     "@types/mock-fs": "^3.6.30",
     "@types/mock-require": "^2.0.0",
@@ -68,6 +69,7 @@
     "fs-extra": "^8.1.0",
     "get-installed-path": "^4.0.8",
     "inversify": "^5.0.1",
+    "jsonschema": "^1.2.4",
     "minimatch": "^3.0.4",
     "nunjucks": "^3.2.0",
     "open": "6.4.0",

schema/docs_gm.json

@@ -0,0 +1,139 @@
+{
+	"definitions": {
+		"rule": {
+			"type": "object",
+			"properties": {
+				"ignore": {
+					"type": "boolean",
+					"title": "Should ignore the script if the script fails the validation rule?",
+					"default": true
+				},
+				"warn": {
+					"type": "boolean",
+					"title": "Should output a warning message if the script fails the validation rule?",
+					"default": true
+				}
+			}
+		}
+	},
+	"$schema": "http://json-schema.org/draft-07/schema#",
+	"type": "object",
+	"properties": {
+	  "name": {
+		"type": "string",
+		"title": "The project's name to display"
+	  },
+	  "output": {
+		"$id": "#/properties/output",
+		"type": "object",
+		"title": "The output configuration",
+		"properties": {
+		  "template": {
+			"type": "string",
+			"title": "The template name to use"
+		  },
+		  "outputFolder": {
+			"type": "string",
+			"title": "The output folder of the documentation"
+		  },
+		  "templatesFolder": {
+			"type": "string",
+			"title": "The folder where the templates are located. If empty, the default templates folder will be used"
+		  },
+		  "scriptPages": {
+			"type": "boolean",
+			"title": "Specifies if individual pages for each gamemaker script sould be generated"
+		  },
+		  "folderPages": {
+			"type": "boolean",
+			"title": "Specifies if individual pages for each gamemaker folder sould be generated"
+		  }
+		}
+	  },
+	  "pattern": {
+		"type": "string",
+		"title": "The glob pattern to use to include files in the project documentation"
+	  },
+	  "root": {
+		"type": "string",
+		"title": "The documentation root folder"
+	  },
+	  "parser": {
+		"type": "object",
+		"title": "The parser configuration",
+		"properties": {
+		  "warnUnrecognizedTags": {
+			"type": "boolean",
+			"title": "Warn about unrecognized JSDoc tags"
+		  },
+		  "mergeDuplicateParams": {
+			"type": "boolean",
+			"title": "If true, the arguments with the same name will be merged."
+		  }
+		}
+	  },
+	  "scripts": {
+		"type": "object",
+		"title": "Rules for validating scripts",
+		"properties": {
+		  "markUnderscoreScriptsAsPrivate": {
+			"type": "boolean",
+			"title": "Mark scripts names starting with underscore as private scripts",
+			"default": false
+		  },
+		  "ignorePrivate": {
+			"type": "boolean",
+			"title": "Ignore private scripts when generating documentation",
+			"default": false
+		  },
+		  "undocumented": {
+            "$ref": "#/definitions/rule",
+			"title": "This rule will fail if the script has undocumented scripts"
+		  },
+		  "mismatchingFunctionName": {
+            "$ref": "#/definitions/rule",
+			"title": "This rule will fail if the script has a mismatching script name and \"function\" JSDoc tags."
+		  },
+		  "noDescription": {
+            "$ref": "#/definitions/rule",
+			"title": "This rule will fail if the script has no description"
+		  },
+		  "undocumentedArguments": {
+            "$ref": "#/definitions/rule",
+			"title": "This rule will fail if the script has undocumented arguments.",
+			"description": "For example, if a script has documentation for 0 arguments, but the GML code uses arguments."
+		  },
+		  "mismatchingArguments": {
+            "$ref": "#/definitions/rule",
+			"title": "This rule will fail if the script has a mismatching number of arguments. ",
+			"description": "For example, if the scripts has documentation for 4 arguments but the GML code uses 6 arguments."
+		  },
+		  "noParamDescription": {
+            "$ref": "#/definitions/rule",
+			"title": "This rule will fail if the script has some argument without description."
+		  },
+		  "noParamType": {
+            "$ref": "#/definitions/rule",
+			"title": "This rule will fail if the script has some argument without argument data type."
+		  },
+		  "functionSignatureInDescription": {
+            "$ref": "#/definitions/rule",
+			"title": "This rule should detect and fail if the \"description\" JSDoc tag has a function signature instead of the actual function description.",
+			"description": "This is because, when you import a GMS1 project into GMS2, the \"description\" tag is filled with the function generated signature."
+		  },
+		  "noReturnDescription": {
+            "$ref": "#/definitions/rule",
+			"title": "This rule fails if the script has a return statement but has not documentation for the returned value"
+		  },
+		  "noReturnType": {
+            "$ref": "#/definitions/rule",
+			"title": "This rule fails if the script has no data type for the returned value"
+		  },
+		  "duplicatedParams": {
+            "$ref": "#/definitions/rule",
+			"title": "This rule fails if the script has one or more duplicated params names"
+		  }
+		}
+	  }
+	}
+  }

schema/template.json

@@ -0,0 +1,59 @@
+{
+	"$schema": "http://json-schema.org/draft-07/schema#",
+	"type": "object",
+	"required": [
+		"name",
+		"author",
+		"description",
+		"web",
+		"pages"
+	],
+	"properties": {
+	  "name": {
+		"type": "string",
+		"title": "The template's name for display",
+		"examples": ["My awesome multicolor template"]
+	  },
+	  "author": {
+		"type": "string",
+		"title": "The author's name"
+	  },
+	  "description": {
+		"type": "string",
+		"title": "A brief description of the template to display"
+	  },
+	  "web": {
+		"type": "string",
+		"title": "The web or repository URL of this template"
+	  },
+	  "copy": {
+		"type": "array",
+		"items": {
+			"type": "string"
+		},
+		"title": "An array of globs string used to determine which files to copy from the template folder.",
+		"description": "template.json, package.json, package-lock.json, and other type of files will never be copied",
+		"default": ["**/*"]
+	  },
+	  "pages": {
+		"type": "object",
+		"title": "The pages ",
+		"required": [
+			"script",
+			"folder"
+		],
+		"properties": {
+		  "script": {
+			"type": "string",
+			"title": "The relative path to the njk file used to render script pages",
+			"examples": ["src/my-script-page.njk"]
+		  },
+		  "folder": {
+			"type": "string",
+			"title": "The relative path to the njk file used to render folder pages",
+			"examples": ["src/my-folder-page.njk"]
+		  }
+		}
+	  }
+	}
+  }

src/SchemaValidator.ts

@@ -0,0 +1,10 @@
+import { injectable } from "inversify";
+import { Validator } from "jsonschema";
+
+@injectable()
+export default class SchemaValidator {
+	public validate(data: any, schema: any): void {
+		const validator = new Validator();
+		validator.validate(data, schema, {throwError: true});
+	}
+}

src/cli/Cli.ts

@@ -61,12 +61,13 @@ export default class Cli {
 
 	private _commandGenerateBuilder(builder: yargs.Argv<IGenerateCommand>, lang: StringsEnglish) {
 		return builder
-			.option("design", {type: "string", describe: lang.OPTION_DESIGN})
 			.option("template", {type: "string", describe: lang.OPTION_TEMPLATE})
 			.option("outputFolder", {type: "string", describe: lang.OPTION_OUTPUT_FOLDER})
 			.option("pattern", {alias: "p", type: "string", describe: lang.OPTION_PATTERN})
 			.option("root", {type: "string", describe: lang.OPTION_ROOT})
-			.option("noOpen", {type: "boolean", default: false, describe: lang.OPTION_NO_OPEN});
+			.option("noOpen", {type: "boolean", default: false, describe: lang.OPTION_NO_OPEN})
+			.option("scriptPages", {type: "boolean", default: true, describe: lang.OPTION_SCRIPT_PAGES})
+			.option("folderPages", {type: "boolean", default: true, describe: lang.OPTION_FOLDER_PAGES});
 	}
 
 	/**

src/cli/CliGenerateFacade.ts

@@ -7,7 +7,7 @@ import * as os from "os";
 import ICliParamsConfig from "../config/ICliParamsConfig";
 import IConfigManager from "../config/IConfigManager";
 import IConfigOverrider from "../config/IConfigOverrider";
-import ProjectConfig from "../config/ProjectConfig";
+import { ProjectConfig } from "../config/ProjectConfig";
 import IDocumentationGenerator from "../generator/IDocumentationGenerator";
 import IGMProjectLoader from "../gm_project/IGMProjectLoader";
 import { IOpen } from "../npmmodules";

src/config/ConfigManager.ts

@@ -1,25 +1,34 @@
-import { injectable } from "inversify";
+import { inject, injectable } from "inversify";
 
 import * as fse from "fs-extra";
 import * as path from "path";
+import SchemaValidator from "../SchemaValidator";
+import { TYPES } from "../types";
 import IConfigManager from "./IConfigManager";
-import IProjectConfig from "./IProjectConfig";
-import ProjectConfig from "./ProjectConfig";
+import { IProjectConfig } from "./IProjectConfig";
+import { ProjectConfig } from "./ProjectConfig";
+
+import schema = require("../../schema/docs_gm.json");
 
 /**
  * This class exports and loads the configuration
  */
 @injectable()
 export default class ConfigManager implements IConfigManager {
 
+	@inject(TYPES.ISchemaValidator)
+	private _schemaValidator: SchemaValidator;
+
 	/**
 	 * Copy the docs_gm.json file to the specified outputPath.
 	 * @param outputPath The output filepath
 	 * @returns A promise with the path of the output file
 	 */
 	public async exportConfig(outputPath: string): Promise<string> {
 		outputPath = path.resolve(outputPath, "docs_gm.json");
-		await fse.writeJSON(outputPath, new ProjectConfig(), {
+		const config = new ProjectConfig();
+		config.name = "Your project name";
+		await fse.writeJSON(outputPath, config, {
 			spaces: "\t",
 		});
 		return outputPath;
@@ -40,12 +49,18 @@ export default class ConfigManager implements IConfigManager {
 		} else {
 			jsonPath = path.resolve(jsonOrProjectPath, "datafiles/docs_gm.json");
 		}
+
+		let data: IProjectConfig;
 		try {
-			const data: IProjectConfig = await fse.readJSON(jsonPath);
-			const config: IProjectConfig = new ProjectConfig();
-			return Object.assign(config, data);
+			data = await fse.readJSON(jsonPath);
 		} catch (e) {
 			return undefined;
 		}
+
+		this._schemaValidator.validate(data, schema);
+
+		const config: IProjectConfig = new ProjectConfig();
+		return Object.assign(config, data);
+
 	}
 }

src/config/ConfigOverrider.ts

@@ -1,6 +1,6 @@
 import { injectable } from "inversify";
 import ICliParamsConfig from "./ICliParamsConfig";
-import IProjectConfig from "./IProjectConfig";
+import { IOutputConfig, IProjectConfig } from "./IProjectConfig";
 
 @injectable()
 export default class ConfigOverrider {
@@ -9,21 +9,31 @@ export default class ConfigOverrider {
 	 * @param config The config
 	 */
 	public override(config: IProjectConfig, overrideConfig: ICliParamsConfig): IProjectConfig {
-		if (overrideConfig.design) {
-			config.output.design = overrideConfig.design;
-		}
-		if (overrideConfig.template) {
-			config.output.template = overrideConfig.template;
-		}
-		if (overrideConfig.outputFolder) {
-			config.output.outputFolder = overrideConfig.outputFolder;
-		}
-		if (overrideConfig.pattern) {
+
+		this._overrideOutputConfig(config.output, overrideConfig);
+
+		if (overrideConfig.pattern !== undefined) {
 			config.pattern = overrideConfig.pattern;
 		}
-		if (overrideConfig.root) {
+		if (overrideConfig.root !== undefined) {
 			config.root = overrideConfig.root;
 		}
+
 		return config;
 	}
+
+	private _overrideOutputConfig(output: IOutputConfig, overrideConfig: ICliParamsConfig): void {
+		if (overrideConfig.template !== undefined) {
+			output.template = overrideConfig.template;
+		}
+		if (overrideConfig.outputFolder !== undefined) {
+			output.outputFolder = overrideConfig.outputFolder;
+		}
+		if (overrideConfig.folderPages !== undefined) {
+			output.folderPages = overrideConfig.folderPages;
+		}
+		if (overrideConfig.scriptPages !== undefined) {
+			output.scriptPages = overrideConfig.scriptPages;
+		}
+	}
 }