AutoForge/src/AutoForge.Core/Vehicles/VehicleProfile.cs

502 lines
20 KiB
C#

namespace AutoForge.Core.Vehicles;
public enum CapabilityStatus
{
Supported,
Unsupported,
Unknown,
Inaccessible,
Restricted
}
public enum EvidenceClassification
{
Verified,
Unverified,
Inferred,
Synthetic
}
public sealed class VehicleIdentity
{
public VehicleIdentity(
string vehicleIdentifier,
string manufacturer,
string model,
int? modelYear = null,
string? trim = null,
string? engine = null,
string? transmission = null,
string? drivetrain = null,
IEnumerable<string>? evidenceReferences = null)
{
VehicleIdentifier = ProfileValidation.RequiredIdentifier(vehicleIdentifier, nameof(vehicleIdentifier));
Manufacturer = ProfileValidation.RequiredText(manufacturer, nameof(manufacturer));
Model = ProfileValidation.RequiredText(model, nameof(model));
if (modelYear is <= 0 or > 9999)
{
throw new ArgumentOutOfRangeException(nameof(modelYear), modelYear, "Model year must be unknown or between 1 and 9999.");
}
ModelYear = modelYear;
Trim = ProfileValidation.OptionalText(trim, nameof(trim));
Engine = ProfileValidation.OptionalText(engine, nameof(engine));
Transmission = ProfileValidation.OptionalText(transmission, nameof(transmission));
Drivetrain = ProfileValidation.OptionalText(drivetrain, nameof(drivetrain));
EvidenceReferences = ProfileValidation.CopyIdentifiers(evidenceReferences, nameof(evidenceReferences));
}
public string VehicleIdentifier { get; }
public string Manufacturer { get; }
public string Model { get; }
public int? ModelYear { get; }
public string? Trim { get; }
public string? Engine { get; }
public string? Transmission { get; }
public string? Drivetrain { get; }
public IReadOnlyList<string> EvidenceReferences { get; }
}
public sealed class EvidenceApplicability
{
public EvidenceApplicability(
string vehicleIdentifier,
int? modelYear = null,
string? profileIdentifier = null,
int? profileRevision = null,
string? moduleInstanceIdentifier = null,
string? hardwareIdentifier = null,
string? softwareIdentifier = null,
string? firmwareIdentifier = null,
string? calibrationIdentifier = null)
{
VehicleIdentifier = ProfileValidation.RequiredIdentifier(vehicleIdentifier, nameof(vehicleIdentifier));
if (modelYear is <= 0 or > 9999)
{
throw new ArgumentOutOfRangeException(nameof(modelYear), modelYear, "Applicable model year must be unknown or between 1 and 9999.");
}
ModelYear = modelYear;
ProfileIdentifier = ProfileValidation.OptionalIdentifier(profileIdentifier, nameof(profileIdentifier));
ModuleInstanceIdentifier = ProfileValidation.OptionalIdentifier(moduleInstanceIdentifier, nameof(moduleInstanceIdentifier));
HardwareIdentifier = ProfileValidation.OptionalIdentifier(hardwareIdentifier, nameof(hardwareIdentifier));
SoftwareIdentifier = ProfileValidation.OptionalIdentifier(softwareIdentifier, nameof(softwareIdentifier));
FirmwareIdentifier = ProfileValidation.OptionalIdentifier(firmwareIdentifier, nameof(firmwareIdentifier));
CalibrationIdentifier = ProfileValidation.OptionalIdentifier(calibrationIdentifier, nameof(calibrationIdentifier));
if ((ProfileIdentifier is null) != (profileRevision is null) || profileRevision is <= 0)
{
throw new ArgumentException(
"Profile applicability must specify both a profile identifier and a positive revision, or neither.",
nameof(profileRevision));
}
if (ModuleInstanceIdentifier is null &&
(HardwareIdentifier is not null || SoftwareIdentifier is not null ||
FirmwareIdentifier is not null || CalibrationIdentifier is not null))
{
throw new ArgumentException(
"Module identity context requires an explicit module instance identifier.",
nameof(moduleInstanceIdentifier));
}
ProfileRevision = profileRevision;
}
public string VehicleIdentifier { get; }
public int? ModelYear { get; }
public string? ProfileIdentifier { get; }
public int? ProfileRevision { get; }
public string? ModuleInstanceIdentifier { get; }
public string? HardwareIdentifier { get; }
public string? SoftwareIdentifier { get; }
public string? FirmwareIdentifier { get; }
public string? CalibrationIdentifier { get; }
}
public sealed class ProfileEvidence
{
public ProfileEvidence(
string evidenceIdentifier,
EvidenceClassification classification,
string sourceReference,
string description,
EvidenceApplicability applicability,
double? confidence = null,
string? verificationInformation = null,
DateTimeOffset? publishedAt = null,
DateTimeOffset? retrievedAt = null,
IEnumerable<string>? limitations = null)
{
EvidenceIdentifier = ProfileValidation.RequiredIdentifier(evidenceIdentifier, nameof(evidenceIdentifier));
if (!Enum.IsDefined(classification))
{
throw new ArgumentOutOfRangeException(nameof(classification), classification, "Specify a defined evidence classification.");
}
Classification = classification;
SourceReference = ProfileValidation.RequiredText(sourceReference, nameof(sourceReference));
Description = ProfileValidation.RequiredText(description, nameof(description));
Applicability = applicability ?? throw new ArgumentNullException(nameof(applicability));
if (confidence is { } value && (!double.IsFinite(value) || value is < 0 or > 1))
{
throw new ArgumentOutOfRangeException(nameof(confidence), confidence, "Confidence must be unknown or finite and between 0 and 1.");
}
Confidence = confidence;
VerificationInformation = ProfileValidation.OptionalText(verificationInformation, nameof(verificationInformation));
PublishedAt = publishedAt;
RetrievedAt = retrievedAt;
Limitations = ProfileValidation.CopyText(limitations, nameof(limitations));
}
public string EvidenceIdentifier { get; }
public EvidenceClassification Classification { get; }
public string SourceReference { get; }
public string Description { get; }
public EvidenceApplicability Applicability { get; }
public double? Confidence { get; }
public string? VerificationInformation { get; }
public DateTimeOffset? PublishedAt { get; }
public DateTimeOffset? RetrievedAt { get; }
public IReadOnlyList<string> Limitations { get; }
}
public sealed class CapabilityDeclaration
{
public CapabilityDeclaration(
string operationIdentifier,
CapabilityStatus status,
string? explanation = null,
IEnumerable<string>? limitations = null,
IEnumerable<string>? evidenceReferences = null)
{
OperationIdentifier = ProfileValidation.RequiredIdentifier(operationIdentifier, nameof(operationIdentifier));
if (!Enum.IsDefined(status))
{
throw new ArgumentOutOfRangeException(nameof(status), status, "Specify a defined capability status.");
}
Status = status;
Explanation = ProfileValidation.OptionalText(explanation, nameof(explanation));
Limitations = ProfileValidation.CopyText(limitations, nameof(limitations));
EvidenceReferences = ProfileValidation.CopyIdentifiers(evidenceReferences, nameof(evidenceReferences));
}
public string OperationIdentifier { get; }
public CapabilityStatus Status { get; }
public string? Explanation { get; }
public IReadOnlyList<string> Limitations { get; }
public IReadOnlyList<string> EvidenceReferences { get; }
}
public sealed class ModuleInstance
{
public ModuleInstance(
string instanceIdentifier,
string role,
string name,
string? hardwareIdentifier = null,
string? softwareIdentifier = null,
string? firmwareIdentifier = null,
string? calibrationIdentifier = null,
IEnumerable<CapabilityDeclaration>? capabilities = null,
IEnumerable<string>? evidenceReferences = null)
{
InstanceIdentifier = ProfileValidation.RequiredIdentifier(instanceIdentifier, nameof(instanceIdentifier));
Role = ProfileValidation.RequiredIdentifier(role, nameof(role));
Name = ProfileValidation.RequiredText(name, nameof(name));
HardwareIdentifier = ProfileValidation.OptionalIdentifier(hardwareIdentifier, nameof(hardwareIdentifier));
SoftwareIdentifier = ProfileValidation.OptionalIdentifier(softwareIdentifier, nameof(softwareIdentifier));
FirmwareIdentifier = ProfileValidation.OptionalIdentifier(firmwareIdentifier, nameof(firmwareIdentifier));
CalibrationIdentifier = ProfileValidation.OptionalIdentifier(calibrationIdentifier, nameof(calibrationIdentifier));
Capabilities = ProfileValidation.CopyItems(capabilities ?? [], nameof(capabilities));
EvidenceReferences = ProfileValidation.CopyIdentifiers(evidenceReferences, nameof(evidenceReferences));
ProfileValidation.EnsureUnique(
Capabilities.Select(capability => capability.OperationIdentifier),
StringComparer.OrdinalIgnoreCase,
"Capability operation identifiers must be unique within a module.");
}
public string InstanceIdentifier { get; }
public string Role { get; }
public string Name { get; }
public string? HardwareIdentifier { get; }
public string? SoftwareIdentifier { get; }
public string? FirmwareIdentifier { get; }
public string? CalibrationIdentifier { get; }
public IReadOnlyList<CapabilityDeclaration> Capabilities { get; }
public IReadOnlyList<string> EvidenceReferences { get; }
public CapabilityAssessment GetCapability(string operationIdentifier)
{
var requested = ProfileValidation.RequiredIdentifier(operationIdentifier, nameof(operationIdentifier));
var declaration = Capabilities.FirstOrDefault(
capability => StringComparer.OrdinalIgnoreCase.Equals(capability.OperationIdentifier, requested));
return declaration is null
? new CapabilityAssessment(
requested,
CapabilityStatus.Unknown,
false,
"No capability declaration exists for this operation.")
: new CapabilityAssessment(
declaration.OperationIdentifier,
declaration.Status,
true,
declaration.Explanation ?? "The capability declaration has no additional explanation.");
}
}
public sealed record CapabilityAssessment(
string OperationIdentifier,
CapabilityStatus Status,
bool IsDeclared,
string Explanation);
public sealed class VehicleProfile
{
public VehicleProfile(
string profileIdentifier,
int revision,
VehicleIdentity vehicle,
IEnumerable<ModuleInstance>? modules,
IEnumerable<ProfileEvidence>? evidence)
{
ProfileIdentifier = ProfileValidation.RequiredIdentifier(profileIdentifier, nameof(profileIdentifier));
if (revision <= 0)
{
throw new ArgumentOutOfRangeException(nameof(revision), revision, "Profile revision must be positive.");
}
Revision = revision;
Vehicle = vehicle ?? throw new ArgumentNullException(nameof(vehicle));
Modules = ProfileValidation.CopyItems(modules, nameof(modules));
Evidence = ProfileValidation.CopyItems(evidence, nameof(evidence));
ProfileValidation.EnsureUnique(
Modules.Select(module => module.InstanceIdentifier),
StringComparer.OrdinalIgnoreCase,
"Module instance identifiers must be unique within a profile revision.");
ProfileValidation.EnsureUnique(
Evidence.Select(item => item.EvidenceIdentifier),
StringComparer.OrdinalIgnoreCase,
"Evidence identifiers must be unique within a profile revision.");
ValidateEvidenceReferences();
}
public string ProfileIdentifier { get; }
public int Revision { get; }
public VehicleIdentity Vehicle { get; }
public IReadOnlyList<ModuleInstance> Modules { get; }
public IReadOnlyList<ProfileEvidence> Evidence { get; }
public ModuleInstance GetModule(string instanceIdentifier)
{
var requested = ProfileValidation.RequiredIdentifier(instanceIdentifier, nameof(instanceIdentifier));
return Modules.FirstOrDefault(
module => StringComparer.OrdinalIgnoreCase.Equals(module.InstanceIdentifier, requested))
?? throw new KeyNotFoundException($"Module instance '{requested}' is not declared in this profile.");
}
private void ValidateEvidenceReferences()
{
var evidenceById = Evidence.ToDictionary(
item => item.EvidenceIdentifier,
StringComparer.OrdinalIgnoreCase);
ValidateReferences(Vehicle.EvidenceReferences, evidenceById, null, "vehicle");
foreach (var module in Modules)
{
ValidateReferences(module.EvidenceReferences, evidenceById, module, $"module '{module.InstanceIdentifier}'");
foreach (var capability in module.Capabilities)
{
ValidateReferences(
capability.EvidenceReferences,
evidenceById,
module,
$"operation '{capability.OperationIdentifier}' on module '{module.InstanceIdentifier}'");
}
}
foreach (var item in Evidence)
{
var scope = item.Applicability;
if (!StringComparer.OrdinalIgnoreCase.Equals(scope.VehicleIdentifier, Vehicle.VehicleIdentifier))
{
throw new ArgumentException(
$"Evidence '{item.EvidenceIdentifier}' applies to vehicle '{scope.VehicleIdentifier}', not '{Vehicle.VehicleIdentifier}'.",
nameof(Evidence));
}
if (scope.ModelYear is { } applicableYear &&
Vehicle.ModelYear is { } vehicleYear &&
applicableYear != vehicleYear)
{
throw new ArgumentException(
$"Evidence '{item.EvidenceIdentifier}' applies to model year {applicableYear}, not {vehicleYear}.",
nameof(Evidence));
}
if (scope.ProfileIdentifier is not null &&
(!StringComparer.OrdinalIgnoreCase.Equals(scope.ProfileIdentifier, ProfileIdentifier) ||
scope.ProfileRevision != Revision))
{
throw new ArgumentException(
$"Evidence '{item.EvidenceIdentifier}' applies to a different profile identity or revision.",
nameof(Evidence));
}
if (scope.ModuleInstanceIdentifier is not null)
{
var module = Modules.FirstOrDefault(
candidate => StringComparer.OrdinalIgnoreCase.Equals(
candidate.InstanceIdentifier,
scope.ModuleInstanceIdentifier));
if (module is null ||
!SameOptional(scope.HardwareIdentifier, module.HardwareIdentifier) ||
!SameOptional(scope.SoftwareIdentifier, module.SoftwareIdentifier) ||
!SameOptional(scope.FirmwareIdentifier, module.FirmwareIdentifier) ||
!SameOptional(scope.CalibrationIdentifier, module.CalibrationIdentifier))
{
throw new ArgumentException(
$"Evidence '{item.EvidenceIdentifier}' has dangling or conflicting module applicability.",
nameof(Evidence));
}
}
}
}
private static void ValidateReferences(
IReadOnlyList<string> references,
IReadOnlyDictionary<string, ProfileEvidence> evidenceById,
ModuleInstance? module,
string context)
{
foreach (var reference in references)
{
if (!evidenceById.TryGetValue(reference, out var item))
{
throw new ArgumentException(
$"Evidence reference '{reference}' for {context} does not resolve within this profile.",
nameof(Evidence));
}
var scope = item.Applicability;
if (scope.ModuleInstanceIdentifier is not null &&
(module is null ||
!StringComparer.OrdinalIgnoreCase.Equals(scope.ModuleInstanceIdentifier, module.InstanceIdentifier)))
{
throw new ArgumentException(
$"Evidence '{reference}' is not applicable to {context}.",
nameof(Evidence));
}
}
}
private static bool SameOptional(string? constraint, string? target) =>
constraint is null ||
(target is not null && StringComparer.OrdinalIgnoreCase.Equals(constraint, target));
}
public sealed class VehicleProfileReference
{
public VehicleProfileReference(string profileIdentifier, int revision)
{
ProfileIdentifier = ProfileValidation.RequiredIdentifier(profileIdentifier, nameof(profileIdentifier));
if (revision <= 0)
{
throw new ArgumentOutOfRangeException(nameof(revision), revision, "Profile revision must be positive.");
}
Revision = revision;
}
public string ProfileIdentifier { get; }
public int Revision { get; }
}
internal static class ProfileValidation
{
public static string RequiredIdentifier(string? value, string parameterName)
{
ArgumentException.ThrowIfNullOrWhiteSpace(value, parameterName);
if (!StringComparer.Ordinal.Equals(value, value.Trim()))
{
throw new ArgumentException("Identifiers must not contain leading or trailing whitespace.", parameterName);
}
return value;
}
public static string? OptionalIdentifier(string? value, string parameterName) =>
value is null ? null : RequiredIdentifier(value, parameterName);
public static string RequiredText(string? value, string parameterName)
{
ArgumentException.ThrowIfNullOrWhiteSpace(value, parameterName);
if (!StringComparer.Ordinal.Equals(value, value.Trim()))
{
throw new ArgumentException("Text values must not contain leading or trailing whitespace.", parameterName);
}
return value;
}
public static string? OptionalText(string? value, string parameterName) =>
value is null ? null : RequiredText(value, parameterName);
public static IReadOnlyList<string> CopyIdentifiers(IEnumerable<string>? values, string parameterName)
{
var copy = values?.Select(value => RequiredIdentifier(value, parameterName)).ToArray() ?? [];
EnsureUnique(copy, StringComparer.OrdinalIgnoreCase, $"{parameterName} must not contain duplicates.");
return Array.AsReadOnly(copy);
}
public static IReadOnlyList<string> CopyText(IEnumerable<string>? values, string parameterName)
{
var copy = values?.Select(value => RequiredText(value, parameterName)).ToArray() ?? [];
return Array.AsReadOnly(copy);
}
public static IReadOnlyList<T> CopyItems<T>(IEnumerable<T>? values, string parameterName)
where T : class
{
if (values is null)
{
throw new ArgumentNullException(parameterName);
}
var copy = values.ToArray();
if (copy.Any(item => item is null))
{
throw new ArgumentException("Collections must not contain null items.", parameterName);
}
return Array.AsReadOnly(copy);
}
public static void EnsureUnique(IEnumerable<string> values, StringComparer comparer, string message)
{
var set = new HashSet<string>(comparer);
foreach (var value in values)
{
if (!set.Add(value))
{
throw new ArgumentException(message);
}
}
}
}