From 3ba567eaddeaa0bb2bdd749b56e0601d1cf65a25 Mon Sep 17 00:00:00 2001 From: Jesse Plamondon-Willard Date: Sun, 4 Aug 2019 03:28:34 -0400 Subject: add JSON validator with initial support for manifest format (#654) --- src/SMAPI.Web/Views/JsonValidator/Index.cshtml | 126 +++++++++++++++++++++++++ src/SMAPI.Web/Views/Shared/_Layout.cshtml | 7 +- 2 files changed, 132 insertions(+), 1 deletion(-) create mode 100644 src/SMAPI.Web/Views/JsonValidator/Index.cshtml (limited to 'src/SMAPI.Web/Views') diff --git a/src/SMAPI.Web/Views/JsonValidator/Index.cshtml b/src/SMAPI.Web/Views/JsonValidator/Index.cshtml new file mode 100644 index 00000000..cd7ca912 --- /dev/null +++ b/src/SMAPI.Web/Views/JsonValidator/Index.cshtml @@ -0,0 +1,126 @@ +@using StardewModdingAPI.Web.ViewModels.JsonValidator +@model JsonValidatorModel + +@{ + ViewData["Title"] = "JSON validator"; +} + +@section Head { + @if (Model.PasteID != null) + { + + } + + + + + + + + + +} + +@* upload result banner *@ +@if (Model.UploadError != null) +{ + +} +else if (Model.ParseError != null) +{ + +} +else if (Model.PasteID != null) +{ + +} + +@* upload new file *@ +@if (Model.Content == null) +{ +

Upload a JSON file

+
+
    +
  1. + Choose the JSON format:
    + +
    2. +
  2. + Drag the file onto this textbox (or paste the text in):
    + +
    3. +
  3. + Click this button:
    + +
    4. +
+
+} + +@* validation results *@ +@if (Model.Content != null) +{ +
+ @if (Model.UploadError == null) + { +
+ Change JSON format: + +
+ +

Validation errors

+ @if (Model.Errors.Any()) + { + + + + + + + + @foreach (JsonValidatorErrorModel error in Model.Errors) + { + + + + + + } +
LineFieldError
@error.Line@error.Path@error.Message
+ } + else + { +

No errors found.

+ } + } + +

Raw content

+ 
@Model.Content
+
+} diff --git a/src/SMAPI.Web/Views/Shared/_Layout.cshtml b/src/SMAPI.Web/Views/Shared/_Layout.cshtml index 4c602b29..9911ef0e 100644 --- a/src/SMAPI.Web/Views/Shared/_Layout.cshtml +++ b/src/SMAPI.Web/Views/Shared/_Layout.cshtml @@ -16,9 +16,14 @@

SMAPI

+ +

Tools

+
-- cgit From f24e7428df15ee8bcc9a2a45de98363670e72231 Mon Sep 17 00:00:00 2001 From: Jesse Plamondon-Willard Date: Sun, 4 Aug 2019 15:55:24 -0400 Subject: add line highlighting and linking (#654) --- src/SMAPI.Web/Views/JsonValidator/Index.cshtml | 4 +- .../wwwroot/Content/css/json-validator.css | 4 + src/SMAPI.Web/wwwroot/Content/js/json-validator.js | 123 ++++++++++++++++++++- 3 files changed, 127 insertions(+), 4 deletions(-) (limited to 'src/SMAPI.Web/Views') diff --git a/src/SMAPI.Web/Views/JsonValidator/Index.cshtml b/src/SMAPI.Web/Views/JsonValidator/Index.cshtml index cd7ca912..6658e7b9 100644 --- a/src/SMAPI.Web/Views/JsonValidator/Index.cshtml +++ b/src/SMAPI.Web/Views/JsonValidator/Index.cshtml @@ -107,7 +107,7 @@ else if (Model.PasteID != null) @foreach (JsonValidatorErrorModel error in Model.Errors) { - @error.Line + @error.Line @error.Path @error.Message @@ -121,6 +121,6 @@ else if (Model.PasteID != null) }

Raw content

- 
@Model.Content
+ 
@Model.Content
} diff --git a/src/SMAPI.Web/wwwroot/Content/css/json-validator.css b/src/SMAPI.Web/wwwroot/Content/css/json-validator.css index f9aeb18b..d4a43032 100644 --- a/src/SMAPI.Web/wwwroot/Content/css/json-validator.css +++ b/src/SMAPI.Web/wwwroot/Content/css/json-validator.css @@ -72,6 +72,10 @@ background: #fff; } +#output div.sunlight-line-highlight-active { + background-color: #eeeacc; +} + /********* ** Upload form *********/ diff --git a/src/SMAPI.Web/wwwroot/Content/js/json-validator.js b/src/SMAPI.Web/wwwroot/Content/js/json-validator.js index 3f7a1775..265e0c5e 100644 --- a/src/SMAPI.Web/wwwroot/Content/js/json-validator.js +++ b/src/SMAPI.Web/wwwroot/Content/js/json-validator.js @@ -1,20 +1,139 @@ /* globals $ */ var smapi = smapi || {}; + +/** + * Manages the logic for line range selections. + * @param {int} maxLines The maximum number of lines in the content. + */ +smapi.LineNumberRange = function (maxLines) { + var self = this; + + /** + * @var {int} minLine The first line in the selection, or null if no lines selected. + */ + self.minLine = null; + + /** + * @var {int} maxLine The last line in the selection, or null if no lines selected. + */ + self.maxLine = null; + + /** + * Parse line numbers from a URL hash. + * @param {string} hash the URL hash to parse. + */ + self.parseFromUrlHash = function (hash) { + self.minLine = null; + self.maxLine = null; + + // parse hash + var hashParts = hash.match(/^#L(\d+)(?:-L(\d+))?$/); + if (!hashParts || hashParts.length <= 1) + return; + + // extract min/max lines + self.minLine = parseInt(hashParts[1]); + self.maxLine = parseInt(hashParts[2]) || self.minLine; + }; + + /** + * Generate a URL hash for the current line range. + * @returns {string} The generated URL hash. + */ + self.buildHash = function() { + if (!self.minLine) + return ""; + else if (self.minLine === self.maxLine) + return "#L" + self.minLine; + else + return "#L" + self.minLine + "-L" + self.maxLine; + } + + /** + * Get a list of all selected lines. + * @returns {Array} The selected line numbers. + */ + self.getLinesSelected = function() { + // format + if (!self.minLine) + return []; + + var lines = []; + for (var i = self.minLine; i <= self.maxLine; i++) + lines.push(i); + return lines; + }; + + return self; +}; + +/** + * UI logic for the JSON validator page. + * @param {any} sectionUrl The base JSON validator page URL. + * @param {any} pasteID The Pastebin paste ID for the content being viewed, if any. + */ smapi.jsonValidator = function (sectionUrl, pasteID) { + /** + * The original content element. + */ + var originalContent = $("#raw-content").clone(); + + /** + * The currently highlighted lines. + */ + var selection = new smapi.LineNumberRange(); + /** * Rebuild the syntax-highlighted element. */ var formatCode = function () { - Sunlight.highlightAll(); + // reset if needed + $(".sunlight-container").replaceWith(originalContent.clone()); + + // apply default highlighting + Sunlight.highlightAll({ + lineHighlight: selection.getLinesSelected() + }); + + // fix line links + $(".sunlight-line-number-margin a").each(function() { + var link = $(this); + var lineNumber = parseInt(link.text()); + link + .attr("id", "L" + lineNumber) + .attr("href", "#L" + lineNumber) + .removeAttr("name") + .data("line-number", lineNumber); + }); + }; + + /** + * Scroll the page so the selected range is visible. + */ + var scrollToRange = function() { + if (!selection.minLine) + return; + + var targetLine = Math.max(1, selection.minLine - 5); + $("#L" + targetLine).get(0).scrollIntoView(); }; /** * Initialise the JSON validator page. */ var init = function () { - // code formatting + // set initial code formatting + selection.parseFromUrlHash(location.hash); formatCode(); + scrollToRange(); + + // update code formatting on hash change + $(window).on("hashchange", function() { + selection.parseFromUrlHash(location.hash); + formatCode(); + scrollToRange(); + }); // change format $("#output #format").on("change", function() { -- cgit From ee0ff5687d4002aab20cd91fd28d007d916af36c Mon Sep 17 00:00:00 2001 From: Jesse Plamondon-Willard Date: Sun, 4 Aug 2019 18:01:05 -0400 Subject: add user-friendly doc link & error messages, document validator, improve manifest schema (#654) --- docs/technical/web.md | 37 +++++++++++++++- .../Controllers/JsonValidatorController.cs | 49 +++++++++++++++++++++- .../ViewModels/JsonValidator/JsonValidatorModel.cs | 3 ++ src/SMAPI.Web/Views/JsonValidator/Index.cshtml | 5 +++ src/SMAPI.Web/wwwroot/schemas/manifest.json | 48 ++++++++++++++------- 5 files changed, 124 insertions(+), 18 deletions(-) (limited to 'src/SMAPI.Web/Views') diff --git a/docs/technical/web.md b/docs/technical/web.md index 50799e00..9884fefc 100644 --- a/docs/technical/web.md +++ b/docs/technical/web.md @@ -6,6 +6,7 @@ and update check API. ## Contents * [Overview](#overview) * [Log parser](#log-parser) + * [JSON validator](#json-validator) * [Web API](#web-api) * [For SMAPI developers](#for-smapi-developers) * [Local development](#local-development) @@ -16,9 +17,41 @@ The `SMAPI.Web` project provides an API and web UI hosted at `*.smapi.io`. ### Log parser The log parser provides a web UI for uploading, parsing, and sharing SMAPI logs. The logs are -persisted in a compressed form to Pastebin. +persisted in a compressed form to Pastebin. The log parser lives at https://log.smapi.io. + +### JSON validator +The JSON validator provides a web UI for uploading and sharing JSON files, and validating them +as plain JSON or against a predefined format like `manifest.json` or Content Patcher's +`content.json`. The JSON validator lives at https://json.smapi.io. + +Schema files are defined in `wwwroot/schemas` using the [JSON Schema](https://json-schema.org/) +format, with some special properties: +* The root schema may have a `@documentationURL` field, which is the URL to the user-facing + documentation for the format (if any). +* Any part of the schema can define an `@errorMessages` field, which specifies user-friendly errors + which override the auto-generated messages. These are indexed by error type. For example: + ```js + "pattern": "^[a-zA-Z0-9_.-]+\\.dll$", + "@errorMessages": { + "pattern": "Invalid value; must be a filename ending with .dll." + } + ``` + +You can also reference these schemas in your JSON file directly using the `$schema` field, for +text editors that support schema validation. For example: +```js +{ + "$schema": "https://smapi.io/schemas/manifest.json", + "Name": "Some mod", + ... +} +``` + +Current schemas: -The log parser lives at https://log.smapi.io. +format | schema URL +------ | ---------- +[SMAPI `manifest.json`](https://stardewvalleywiki.com/Modding:Modder_Guide/APIs/Manifest) | https://smapi.io/schemas/manifest.json ### Web API SMAPI provides a web API at `api.smapi.io` for use by SMAPI and external tools. The URL includes a diff --git a/src/SMAPI.Web/Controllers/JsonValidatorController.cs b/src/SMAPI.Web/Controllers/JsonValidatorController.cs index 37393a98..7b755d3b 100644 --- a/src/SMAPI.Web/Controllers/JsonValidatorController.cs +++ b/src/SMAPI.Web/Controllers/JsonValidatorController.cs @@ -113,6 +113,9 @@ namespace StardewModdingAPI.Web.Controllers schema = JSchema.Parse(System.IO.File.ReadAllText(schemaFile.FullName)); } + // get format doc URL + result.FormatUrl = this.GetExtensionField(schema, "@documentationUrl"); + // validate JSON parsed.IsValid(schema, out IList rawErrors); var errors = rawErrors @@ -172,13 +175,22 @@ namespace StardewModdingAPI.Web.Controllers /// The indentation level to apply for inner errors. private string GetFlattenedError(ValidationError error, int indent = 0) { + // get override error + string message = this.GetOverrideError(error.Schema, error.ErrorType); + if (message != null) + return message; + // get friendly representation of main error - string message = error.Message; + message = error.Message; switch (error.ErrorType) { case ErrorType.Enum: message = $"Invalid value. Found '{error.Value}', but expected one of '{string.Join("', '", error.Schema.Enum)}'."; break; + + case ErrorType.Required: + message = $"Missing required fields: {string.Join(", ", (List)error.Value)}."; + break; } // add inner errors @@ -216,5 +228,40 @@ namespace StardewModdingAPI.Web.Controllers return null; } + + /// Get an override error from the JSON schema, if any. + /// The schema or subschema that raised the error. + /// The error type. + private string GetOverrideError(JSchema schema, ErrorType errorType) + { + // get override errors + IDictionary errors = this.GetExtensionField>(schema, "@errorMessages"); + if (errors == null) + return null; + errors = new Dictionary(errors, StringComparer.InvariantCultureIgnoreCase); + + // get matching error + return errors.TryGetValue(errorType.ToString(), out string errorPhrase) + ? errorPhrase + : null; + } + + /// Get an extension field from a JSON schema. + /// The field type. + /// The schema whose extension fields to search. + /// The case-insensitive field key. + private T GetExtensionField(JSchema schema, string key) + { + if (schema.ExtensionData != null) + { + foreach (var pair in schema.ExtensionData) + { + if (pair.Key.Equals(key, StringComparison.InvariantCultureIgnoreCase)) + return pair.Value.ToObject(); + } + } + + return default; + } } } diff --git a/src/SMAPI.Web/ViewModels/JsonValidator/JsonValidatorModel.cs b/src/SMAPI.Web/ViewModels/JsonValidator/JsonValidatorModel.cs index 4c122d4f..2d13bf23 100644 --- a/src/SMAPI.Web/ViewModels/JsonValidator/JsonValidatorModel.cs +++ b/src/SMAPI.Web/ViewModels/JsonValidator/JsonValidatorModel.cs @@ -33,6 +33,9 @@ namespace StardewModdingAPI.Web.ViewModels.JsonValidator /// An error which occurred while parsing the JSON. public string ParseError { get; set; } + /// A web URL to the user-facing format documentation. + public string FormatUrl { get; set; } + /********* ** Public methods diff --git a/src/SMAPI.Web/Views/JsonValidator/Index.cshtml b/src/SMAPI.Web/Views/JsonValidator/Index.cshtml index 6658e7b9..5c3168e5 100644 --- a/src/SMAPI.Web/Views/JsonValidator/Index.cshtml +++ b/src/SMAPI.Web/Views/JsonValidator/Index.cshtml @@ -95,6 +95,11 @@ else if (Model.PasteID != null)

Validation errors

+ @if (Model.FormatUrl != null) + { +

See format documentation.

+ } + @if (Model.Errors.Any()) { diff --git a/src/SMAPI.Web/wwwroot/schemas/manifest.json b/src/SMAPI.Web/wwwroot/schemas/manifest.json index 06173333..804eb53d 100644 --- a/src/SMAPI.Web/wwwroot/schemas/manifest.json +++ b/src/SMAPI.Web/wwwroot/schemas/manifest.json @@ -3,6 +3,7 @@ "$id": "https://smapi.io/schemas/manifest.json", "title": "SMAPI manifest", "description": "Manifest file for a SMAPI mod or content pack", + "@documentationUrl": "https://stardewvalleywiki.com/Modding:Modder_Guide/APIs/Manifest", "type": "object", "properties": { "Name": { @@ -38,7 +39,10 @@ "description": "The DLL filename SMAPI should load for this mod. Mutually exclusive with ContentPackFor.", "type": "string", "pattern": "^[a-zA-Z0-9_.-]+\\.dll$", - "examples": "LookupAnything.dll" + "examples": "LookupAnything.dll", + "@errorMessages": { + "pattern": "Invalid value; must be a filename ending with .dll." + } }, "ContentPackFor": { "title": "Content pack for", @@ -59,12 +63,17 @@ "required": [ "UniqueID" ] }, + "MinimumApiVersion": { + "title": "Minimum API version", + "description": "The minimum SMAPI version needed to use this mod. If a player tries to use the mod with an older SMAPI version, they'll see a friendly message saying they need to update SMAPI. This also serves as a proxy for the minimum game version, since SMAPI itself enforces a minimum game version.", + "$ref": "#/definitions/SemanticVersion" + }, "Dependencies": { "title": "Mod dependencies", "description": "Specifies other mods to load before this mod. If a dependency is required and a player tries to use the mod without the dependency installed, the mod won't be loaded and they'll see a friendly message saying they need to install those.", "type": "array", "items": { - "type": "object", + "type": "object", "properties": { "UniqueID": { "title": "Dependency unique ID", @@ -90,8 +99,26 @@ "type": "array", "items": { "type": "string", - "pattern": "^(Chucklefish:\\d+|Nexus:\\d+|GitHub:[A-Za-z0-9_]+/[A-Za-z0-9_]+|ModDrop:\\d+)$" + "pattern": "^(Chucklefish:\\d+|Nexus:\\d+|GitHub:[A-Za-z0-9_]+/[A-Za-z0-9_]+|ModDrop:\\d+)$", + "@errorMessages": { + "pattern": "Invalid update key; see https://stardewvalleywiki.com/Modding:Modder_Guide/APIs/Manifest#Update_checks for more info." + } + } + } + }, + "definitions": { + "SemanticVersion": { + "type": "string", + "pattern": "^(?>(?0|[1-9]\\d*))\\.(?>(?0|[1-9]\\d*))(?>(?:\\.(?0|[1-9]\\d*))?)(?:-(?(?>[a-zA-Z0-9]+[\\-\\.]?)+))?$", // derived from SMAPI.Toolkit.SemanticVersion + "examples": [ "1.0.0", "1.0.1-beta.2" ], + "@errorMessages": { + "pattern": "Invalid semantic version; must be formatted like 1.2.0 or 1.2.0-prerelease.tags. See https://semver.org/ for more info." } + }, + "ModID": { + "type": "string", + "pattern": "^[a-zA-Z0-9_.-]+$", // derived from SMAPI.Toolkit.Utilities.PathUtilities.IsSlug + "examples": [ "Pathoschild.LookupAnything" ] } }, @@ -104,17 +131,8 @@ "required": [ "ContentPackFor" ] } ], - - "definitions": { - "SemanticVersion": { - "type": "string", - "pattern": "(?>(?0|[1-9]\\d*))\\.(?>(?0|[1-9]\\d*))(?>(?:\\.(?0|[1-9]\\d*))?)(?:-(?(?>[a-zA-Z0-9]+[\\-\\.]?)+))?", // derived from SMAPI.Toolkit.SemanticVersion - "examples": [ "1.0.0", "1.0.1-beta.2" ] - }, - "ModID": { - "type": "string", - "pattern": "^[a-zA-Z0-9_.-]+$", // derived from SMAPI.Toolkit.Utilities.PathUtilities.IsSlug - "examples": [ "Pathoschild.LookupAnything" ] - } + "additionalProperties": false, + "@errorMessages": { + "oneOf": "Can't specify both EntryDll or ContentPackFor, they're mutually exclusive." } } -- cgit