502 lines
20 KiB
C#
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);
|
|
}
|
|
}
|
|
}
|
|
}
|