Framework/Scripting/Addons/AddonManifest.cs

The addon.json manifest model for a roleplay framework's Lua addon system, plus a VersionConstraint helper. Holds id, title, version, apiVersion, entry files, dependencies, gamemodes and content packages, validates them against the folder name and framework Lua API version, and parses/satisfies semver range constraints like >=1.2.0 and ^1.0.0.

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text.RegularExpressions;
using RoleplayFramework.Core;

namespace RoleplayFramework.Scripting;

/// <summary>
/// <c>lua/addons/&lt;id&gt;/addon.json</c>: an addon is Lua that runs on top of whatever gamemode the server uses
/// (a chat command, a HUD widget, an admin tool, ...). Server owners drop the folder into their data folder and switch
/// it on or off per server in framework.json (<c>"DisabledAddons"</c>).
///
/// <code>
/// { "id": "roll", "title": "Dice Roll", "version": "1.0.0", "apiVersion": 1,
///   "dependencies": { "otheraddon": "&gt;=1.2.0" },     // other addons, with an optional version constraint
///   "gamemodes": [ "base" ],                          // only with these gamemodes (or gamemodes deriving from them)
///   "entry": { "shared": "sh_init.lua" },             // optional; default: every sh_/sv_/cl_ file in the folder
///   "packages": [], "collections": [] }
/// </code>
/// </summary>
public sealed class AddonManifest
{
	[System.Text.Json.Serialization.JsonPropertyName( "id" )]
	public string Id { get; set; }
	[System.Text.Json.Serialization.JsonPropertyName( "title" )]
	public string Title { get; set; }
	[System.Text.Json.Serialization.JsonPropertyName( "version" )]
	public string Version { get; set; }
	[System.Text.Json.Serialization.JsonPropertyName( "apiVersion" )]
	public int ApiVersion { get; set; }
	[System.Text.Json.Serialization.JsonPropertyName( "author" )]
	public string Author { get; set; }
	[System.Text.Json.Serialization.JsonPropertyName( "description" )]
	public string Description { get; set; }

	/// <summary>Optional entry files (relative to the addon folder). Without it, every top-level sh_/sv_/cl_ file loads.</summary>
	[System.Text.Json.Serialization.JsonPropertyName( "entry" )]
	public GamemodeEntry Entry { get; set; }

	/// <summary>Other addons this one needs: id → version constraint ("" or "*" = any version).</summary>
	[System.Text.Json.Serialization.JsonPropertyName( "dependencies" )]
	public Dictionary<string, string> Dependencies { get; set; } = new();

	/// <summary>Gamemodes this addon works with; matches the active gamemode or any gamemode it derives from. Empty = all.</summary>
	[System.Text.Json.Serialization.JsonPropertyName( "gamemodes" )]
	public List<string> Gamemodes { get; set; } = new();

	[System.Text.Json.Serialization.JsonPropertyName( "packages" )]
	public List<string> Packages { get; set; } = new();

	[System.Text.Json.Serialization.JsonPropertyName( "collections" )]
	public List<string> Collections { get; set; } = new();

	/// <summary>Folder the manifest was found in, e.g. "lua/addons/roll". Set by discovery.</summary>
	[System.Text.Json.Serialization.JsonIgnore]
	public string Root { get; set; }

	static readonly Regex VersionPattern = new( @"^\d+\.\d+\.\d+([-+][0-9A-Za-z.\-]+)?$" );

	public static bool IsValidVersion( string v ) => v is not null && VersionPattern.IsMatch( v );

	public List<string> Validate( string folderName )
	{
		var e = new List<string>();

		if ( string.IsNullOrEmpty( Id ) ) e.Add( "missing 'id'" );
		else if ( !FrameworkConfig.IsValidId( Id ) ) e.Add( $"'id' \"{Id}\" must be 1-32 characters of a-z, 0-9 or _" );
		else if ( Id != folderName ) e.Add( $"'id' \"{Id}\" must match its folder name \"{folderName}\"" );

		if ( string.IsNullOrWhiteSpace( Title ) ) e.Add( "missing 'title'" );
		else if ( Title.Length > 64 ) e.Add( "'title' is longer than 64 characters" );

		if ( string.IsNullOrEmpty( Version ) ) e.Add( "missing 'version'" );
		else if ( !IsValidVersion( Version ) ) e.Add( $"'version' \"{Version}\" is not semver (e.g. 1.2.0)" );

		if ( ApiVersion == 0 ) e.Add( "missing 'apiVersion'" );
		else if ( ApiVersion != FrameworkInfo.LuaApiVersion )
			e.Add( $"'apiVersion' {ApiVersion} is not supported (this framework provides Lua API v{FrameworkInfo.LuaApiVersion})" );

		if ( Entry is not null )
		{
			if ( Entry.Shared is null && Entry.Server is null && Entry.Client is null ) e.Add( "'entry' needs at least one of shared/server/client (or leave it out to load every file)" );
			CheckEntry( e, "shared", Entry.Shared, "sh_" );
			CheckEntry( e, "server", Entry.Server, "sv_" );
			CheckEntry( e, "client", Entry.Client, "cl_" );
		}

		Dependencies ??= new();
		if ( Dependencies.Count > 32 ) e.Add( "more than 32 dependencies" );
		foreach ( var (dep, constraint) in Dependencies )
		{
			if ( !FrameworkConfig.IsValidId( dep ) ) e.Add( $"dependency \"{dep}\" is not a valid addon id" );
			else if ( dep == Id ) e.Add( "an addon cannot depend on itself" );
			if ( VersionConstraint.Check( constraint ) is { } bad ) e.Add( $"dependency \"{dep}\": {bad}" );
		}

		Gamemodes ??= new();
		foreach ( var g in Gamemodes )
			if ( !FrameworkConfig.IsValidId( g ) ) e.Add( $"gamemodes: \"{g}\" is not a valid gamemode id" );

		foreach ( var pkg in Packages ?? new List<string>() )
			if ( !ContentPackages.IsValidIdent( ContentPackages.Normalize( pkg ) ) ) e.Add( $"packages: '{pkg}' is not an org.name package ident" );
		foreach ( var c in Collections ?? new List<string>() )
			if ( ContentPackages.CheckCollectionSource( c ) is { } bad ) e.Add( $"collections: {bad}" );

		return e;
	}

	static void CheckEntry( List<string> e, string realm, string path, string prefix )
	{
		if ( path is null ) return;
		var err = LuaPaths.CheckRelative( path );
		if ( err is not null ) { e.Add( $"entry.{realm} \"{path}\": {err}" ); return; }
		var file = path.Substring( path.LastIndexOf( '/' ) + 1 );
		if ( !file.StartsWith( prefix ) ) e.Add( $"entry.{realm} \"{path}\" must be a {prefix}*.lua file" );
	}
}

/// <summary>
/// Version constraints for addon dependencies. Space-separated parts that must all hold:
/// <c>*</c> or empty (any), <c>1.2.0</c> or <c>=1.2.0</c> (exactly), <c>&gt;=1.2.0</c>, <c>&gt;1.2.0</c>, <c>&lt;=2.0.0</c>,
/// <c>&lt;2.0.0</c>, <c>^1.2.0</c> (1.2.0 up to, not including, 2.0.0), <c>~1.2.0</c> (1.2.0 up to 1.3.0).
/// </summary>
public static class VersionConstraint
{
	static readonly Regex Part = new( @"^(>=|<=|>|<|=|\^|~)?(\d+\.\d+\.\d+([-+][0-9A-Za-z.\-]+)?)$" );

	/// <summary>Null if the constraint is well-formed, else why not.</summary>
	public static string Check( string constraint )
	{
		if ( constraint is null ) return null;
		if ( constraint.Length > 64 ) return "version constraint longer than 64 characters";
		foreach ( var p in Parts( constraint ) )
			if ( p != "*" && !Part.IsMatch( p ) ) return $"\"{constraint}\" is not a version constraint (e.g. \">=1.2.0\", \"^1.0.0\", \"*\")";
		return null;
	}

	static IEnumerable<string> Parts( string c ) => (c ?? "").Split( ' ', StringSplitOptions.RemoveEmptyEntries );

	public static bool Satisfies( string version, string constraint )
	{
		foreach ( var p in Parts( constraint ) )
		{
			if ( p == "*" ) continue;
			var m = Part.Match( p );
			if ( !m.Success ) return false;
			var op = m.Groups[1].Value;
			var target = m.Groups[2].Value;
			int cmp = LuaSource.CompareVersions( version, target );
			var t = Nums( target );
			bool ok = op switch
			{
				">=" => cmp >= 0,
				">" => cmp > 0,
				"<=" => cmp <= 0,
				"<" => cmp < 0,
				"^" => cmp >= 0 && LuaSource.CompareVersions( version, $"{t[0] + 1}.0.0" ) < 0,
				"~" => cmp >= 0 && LuaSource.CompareVersions( version, $"{t[0]}.{t[1] + 1}.0" ) < 0,
				_ => cmp == 0,
			};
			if ( !ok ) return false;
		}
		return true;
	}

	static int[] Nums( string v ) => v.Split( '-', '+' )[0].Split( '.' ).Select( x => int.TryParse( x, out var n ) ? n : 0 ).ToArray();
}