UA-.NETStandard/tools/Opc.Ua.SourceGeneration.Core/NodesetFile.cs

/* ========================================================================
 * Copyright (c) 2005-2025 The OPC Foundation, Inc. All rights reserved.
 *
 * OPC Foundation MIT License 1.00
 *
 * Permission is hereby granted, free of charge, to any person
 * obtaining a copy of this software and associated documentation
 * files (the "Software"), to deal in the Software without
 * restriction, including without limitation the rights to use,
 * copy, modify, merge, publish, distribute, sublicense, and/or sell
 * copies of the Software, and to permit persons to whom the
 * Software is furnished to do so, subject to the following
 * conditions:
 *
 * The above copyright notice and this permission notice shall be
 * included in all copies or substantial portions of the Software.
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
 * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
 * OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
 * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
 * HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
 * WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
 * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
 * OTHER DEALINGS IN THE SOFTWARE.
 *
 * The complete license agreement can be found here:
 * http://opcfoundation.org/License/MIT/1.00/
 * ======================================================================*/

using System;
using System.Collections.Generic;
using System.Collections.Immutable;
using System.Globalization;
using System.IO;
using System.Linq;
using System.Xml;
using Microsoft.Extensions.Logging;
using Opc.Ua.Export;
using Opc.Ua.Schema.Model;
using Opc.Ua.Types;
using SystemXmlElement = System.Xml.XmlElement;

namespace Opc.Ua.SourceGeneration
{
    /// <summary>
    /// An entry in the collection
    /// </summary>
    public sealed class NodesetFile
    {
        /// <summary>
        /// Nodeset information
        /// </summary>
        public NodesetFileOptions? Info { get; init; }

        /// <summary>
        /// File name
        /// </summary>
        public string? FileName { get; init; }

        /// <summary>
        /// The nodeset parsed
        /// </summary>
        public UANodeSet? NodeSet { get; init; }

        /// <summary>
        /// Previous versions
        /// </summary>
        internal List<NodesetFile>? PreviousVersions { get; set; }

        /// <summary>
        /// The ModelVersion used to order editions of the model: the item
        /// metadata Version when set, otherwise the ModelTableEntry
        /// ModelVersion (OPC 10000-6 F.2). Null when neither declares one.
        /// </summary>
        internal string? ModelVersion { get; init; }
    }

    /// <summary>
    /// Nodeset information
    /// </summary>
    public sealed record class NodesetFileOptions
    {
        /// <summary>
        /// Model uri
        /// </summary>
        public string? ModelUri { get; init; }

        /// <summary>
        /// Name
        /// </summary>
        public string? Name { get; init; }

        /// <summary>
        /// Prefix to use
        /// </summary>
        public string? Prefix { get; init; }

        /// <summary>
        /// Should be ignored
        /// </summary>
        public bool Ignore { get; init; }

        /// <summary>
        /// Version
        /// </summary>
        public string? Version { get; init; }

        /// <summary>
        /// Optional identifier CSV explicitly associated with this NodeSet.
        /// </summary>
        public string? IdentifierFile { get; init; }
    }

    /// <summary>
    /// Nodeset compiler
    /// </summary>
    public sealed class NodesetFileCollection
    {
        /// <summary>
        /// The files in the collection
        /// </summary>
        public Dictionary<string, string> Files => m_nodesets
            .ToDictionary(x => x.Key, x => x.Value.FileName!);

        /// <summary>
        /// The path of every file identified as a NodeSet2 input, including the
        /// superseded versions <see cref="Files"/> hides behind the winning one
        /// and the ones that failed to load. Callers use this to tell NodeSet2
        /// inputs apart from ModelDesign inputs: a superseded NodeSet is still a
        /// NodeSet and must not be generated a second time by the ModelDesign
        /// pass, and a NodeSet that failed to load is still not a ModelDesign -
        /// handing it to the ModelDesign pass only turns a skipped file into a
        /// second, more confusing failure.
        /// </summary>
        public IEnumerable<string> AllFilePaths => m_nodesetPaths;

        /// <summary>
        /// The models in the collection
        /// </summary>
        public IEnumerable<string> ModelUris => m_nodesets.Values
            .Where(x => !x.Info!.Ignore)
            .Select(x => x.Info!.ModelUri!)
            .Where(x => !string.IsNullOrEmpty(x));

        /// <summary>
        /// The design file entries for every nodeset in the collection,
        /// encoded as <c>"{file},{prefix},{name}"</c> (the same encoding
        /// used by <see cref="GetDesignFileListForModel"/>). These are
        /// suitable for use as <c>Dependencies</c> of a ModelDesign
        /// generation pass so that a ModelDesign referencing a type
        /// defined in a NodeSet2 input can resolve it. The built-in OpcUa
        /// namespace and ignored nodesets are excluded.
        /// </summary>
        public IEnumerable<string> DesignFileEntries => m_nodesets.Values
            .Where(x => !x.Info!.Ignore && x.Info.ModelUri != Namespaces.OpcUa)
            .Select(x => $"{x.FileName},{x.Info!.Prefix},{x.Info.Name}");

        /// <summary>
        /// The identifier CSV files claimed by a NodeSet through its
        /// <c>IdentifierFile</c> metadata. They belong to that NodeSet and must
        /// not be picked up as the identifier file of a ModelDesign input.
        /// </summary>
        public IEnumerable<string> IdentifierFilePaths => m_identifierFiles
            .Select(entry => entry.IdentifierFile);

        /// <summary>
        /// Identifier sidecar validation errors discovered while loading NodeSets.
        /// </summary>
        public IReadOnlyList<NodesetIdentifierValidationError> IdentifierValidationErrors
            => m_identifierValidationErrors;

        /// <summary>
        /// Create collection
        /// </summary>
        public NodesetFileCollection(
            ImmutableArray<(string, NodesetFileOptions)> nodeset2Files,
            IReadOnlyList<string> csvFiles,
            IFileSystem fileSystem,
            ITelemetryContext telemetry)
        {
            m_logger = telemetry.CreateLogger<NodesetFileCollection>();
            foreach ((string file, NodesetFileOptions options) in nodeset2Files)
            {
                try
                {
                    if (!NodeSetToModelDesign.IsNodeSet(fileSystem, file))
                    {
                        continue;
                    }

                    // Positively identified as a NodeSet2 input. Record it
                    // before the load is attempted: a file that fails to load
                    // is still not a ModelDesign, and letting it fall through
                    // to the ModelDesign pass turns a skipped file into a
                    // second failure that aborts the whole pass.
                    m_nodesetPaths.Add(file);

                    using Stream istrm = fileSystem.OpenRead(file);
                    SystemContext systemContext = new(telemetry)
                    {
                        NamespaceUris = new NamespaceTable(),
                        ServerUris = new StringTable()
                    };
                    var nodeset = UANodeSet.Read(istrm);
#if !SKIP_NODE_STATE_LOADING
                    var collection = new NodeStateCollection();
                    try
                    {
                        nodeset!.Import(systemContext, collection);
                    }
                    catch (Exception e)
                    {
                        m_logger.LogError(e, "NodeSet could not be loaded ({File})", file);
                        // Skip this NodeSet, not every remaining one - the other
                        // inputs are independent and must still be loaded.
                        continue;
                    }
#endif
                    if (nodeset.Models == null ||
                        nodeset.Models.Length == 0 ||
                        string.IsNullOrEmpty(nodeset.Models[0].ModelUri))
                    {
                        m_logger.LogError("NodeSet is missing model definition ({File}).", file);
                        continue;
                    }

                    ModelTableEntry model = nodeset.Models[0];
                    if (!Uri.IsWellFormedUriString(model.ModelUri, UriKind.Absolute))
                    {
                        m_logger.LogError(
                           "NodeSet ModelURI is not valid ({ModelUri}).", model.ModelUri);
                        continue;
                    }

                    // The model URI is the one the NodeSet declares. An item
                    // ModelUri that differs cannot rename the model - the nodes
                    // stay in the NodeSet's namespace, and the collection is
                    // keyed and its dependencies resolved by the declared URI -
                    // so honouring it made the model vanish without a word.
                    if (!string.IsNullOrEmpty(options.ModelUri) &&
                        !string.Equals(options.ModelUri, model.ModelUri, StringComparison.Ordinal))
                    {
                        m_logger.LogWarning(
                            "NodeSet ({File}) declares model URI {DeclaredModelUri}, " +
                            "which differs from the ModelUri item metadata {ModelUri}. " +
                            "The declared model URI is used.",
                            file,
                            model.ModelUri,
                            options.ModelUri);
                    }

                    // Get a sane name and prefix
                    string name = GetDefaultNameFromUri(model.ModelUri);
                    string prefix = GetDefaultPrefixFromUri(model.ModelUri);
                    var info = new NodesetFile
                    {
                        FileName = file,
                        NodeSet = nodeset,
                        // OPC 10000-6 F.2 Table F.1: editions are ordered by the
                        // SemVer ModelVersion; the Version attribute is "not
                        // intended for programmatic comparisons".
                        ModelVersion = FirstNonEmpty(options.Version, model.ModelVersion),
                        Info = new NodesetFileOptions // Set reasonable defaults if not provided
                        {
                            ModelUri = model.ModelUri,
                            // A label only; ordering uses ModelVersion above.
                            Version = FirstNonEmpty(
                                options.Version,
                                model.ModelVersion,
                                model.Version,
                                model.PublicationDate.ToString(
                                    "yyyy-MM-dd", CultureInfo.InvariantCulture)),
                            Name = !string.IsNullOrEmpty(options.Name) ?
                                options.Name : name,
                            Prefix = !string.IsNullOrEmpty(options.Prefix) ?
                                options.Prefix : prefix,
                            Ignore = options.Ignore,
                            IdentifierFile = options.IdentifierFile
                        }
                    };

                    if (!string.IsNullOrWhiteSpace(options.IdentifierFile))
                    {
                        string? identifierFile = NodesetIdentifierFileValidator.ResolvePath(
                            file,
                            options.IdentifierFile,
                            csvFiles);
                        if (identifierFile == null)
                        {
                            m_identifierValidationErrors.Add(
                                NodesetIdentifierValidationError.MissingFile(
                                    file,
                                    options.IdentifierFile));
                        }
                        else
                        {
                            m_identifierFiles.Add((info, identifierFile));
                        }
                    }

                    if (m_nodesets.TryGetValue(model.ModelUri, out NodesetFile? existing))
                    {
                        // Keep the newest version under the model URI and record
                        // the superseded one. Replacing unconditionally used to
                        // drop a newer NodeSet that happened to be read first.
                        if (CompareVersions(existing, info) < 0)
                        {
                            info.PreviousVersions = [];

                            if (existing.PreviousVersions != null)
                            {
                                info.PreviousVersions.AddRange(existing.PreviousVersions);
                            }

                            existing.PreviousVersions = null;
                            info.PreviousVersions.Add(existing);
                            m_nodesets[model.ModelUri] = info;
                        }
                        else
                        {
                            existing.PreviousVersions ??= [];
                            existing.PreviousVersions.Add(info);
                        }
                        continue;
                    }
                    m_nodesets[model.ModelUri] = info;
                }
                catch (Exception ex)
                {
                    if (m_logger.IsEnabled(LogLevel.Critical))
                    {
                        m_logger.LogCritical(ex, "Could not parse NodeSet ({File}).", file);
                    }
                }
            }

            foreach (IGrouping<string, (NodesetFile NodeSet, string IdentifierFile)> group in
                m_identifierFiles
                    .GroupBy(entry => entry.IdentifierFile, StringComparer.Ordinal)
                    .OrderBy(entry => entry.Key, StringComparer.Ordinal))
            {
                if (group.Count() > 1)
                {
                    foreach ((NodesetFile nodeset, string identifierFile) in group
                        .OrderBy(entry => entry.NodeSet.FileName, StringComparer.Ordinal))
                    {
                        m_identifierValidationErrors.Add(
                            NodesetIdentifierValidationError.AssignedToMultipleModels(
                                nodeset.FileName!,
                                identifierFile));
                    }
                    continue;
                }

                (NodesetFile singleNodeset, string singleIdentifierFile) = group.Single();
                m_identifierValidationErrors.AddRange(
                    NodesetIdentifierFileValidator.Validate(
                        fileSystem,
                        singleNodeset.FileName!,
                        singleNodeset.Info!.ModelUri!,
                        singleIdentifierFile,
                        telemetry));
            }
        }

        /// <summary>
        /// Get nodeset and dependencies for the model uri
        /// </summary>
        /// <returns></returns>
        public List<string>? GetDesignFileListForModel(
            string modelUri,
            out NodesetFile nodeset,
            IReadOnlyDictionary<string, ModelDependencyReference>? referencedModels = null)
        {
            if (!m_nodesets.TryGetValue(modelUri, out nodeset!))
            {
                return null;
            }

            // Seed the visited set with the root: a dependency that lists the
            // root among its own NamespaceUris (mutual references) must not
            // add the root a second time.
            Dictionary<string, NodesetFile> dependencies = new(StringComparer.Ordinal)
            {
                [nodeset.Info!.ModelUri!] = nodeset
            };
            if (!CollectDependencies(nodeset, dependencies, referencedModels))
            {
                return null;
            }

            NodesetFile root = nodeset;
            List<string> files = [$"{root.FileName},{root.Info.Prefix},{root.Info.Name}"];
            foreach (NodesetFile dependency in dependencies.Values
                .Where(x => !ReferenceEquals(x, root) && x.Info!.ModelUri != Namespaces.OpcUa))
            {
                files.Add($"{dependency.FileName},{dependency.Info!.Prefix},{dependency.Info.Name}");
            }
            return files;
        }

        /// <summary>
        /// Collect dependencies
        /// </summary>
        private bool CollectDependencies(
            NodesetFile target,
            Dictionary<string, NodesetFile> dependencies,
            IReadOnlyDictionary<string, ModelDependencyReference>? referencedModels)
        {
            if (target.NodeSet!.NamespaceUris == null)
            {
                return true;
            }

            foreach (string ns in target.NodeSet.NamespaceUris)
            {
                if (dependencies.ContainsKey(ns) || ns == target.Info!.ModelUri)
                {
                    continue;
                }

                if (!m_nodesets.TryGetValue(ns, out NodesetFile? nodeset))
                {
                    if (IsRuntimeRoleNamespace(target.NodeSet, ns))
                    {
                        continue;
                    }
                    if (referencedModels != null && referencedModels.ContainsKey(ns))
                    {
                        // Dependency is supplied by a referenced assembly's
                        // generated code; not present in AdditionalFiles is
                        // expected. Skip without erroring.
                        if (m_logger.IsEnabled(LogLevel.Information))
                        {
                            m_logger.LogInformation(
                                "NodeSet ({ModelUri}) dependency ({Namespace}) " +
                                "satisfied by referenced assembly.",
                                target.Info.ModelUri,
                                ns);
                        }
                        continue;
                    }

                    m_logger.LogError(
                        "NodeSet ({ModelUri}) dependency is missing ({Namespace}).",
                        target.Info.ModelUri,
                        ns);
                    return false;
                }

                // favour the version in the same directory as the target.
                if (nodeset.PreviousVersions != null &&
                    Path.GetDirectoryName(nodeset.FileName) !=
                        Path.GetDirectoryName(target.FileName))
                {
                    foreach (NodesetFile ii in nodeset.PreviousVersions)
                    {
                        if (Path.GetDirectoryName(ii.FileName) ==
                                Path.GetDirectoryName(target.FileName))
                        {
                            nodeset = ii;
                            break;
                        }
                    }
                }

                dependencies[ns] = nodeset;
                if (!CollectDependencies(nodeset, dependencies, referencedModels))
                {
                    return false;
                }
            }
            return true;
        }

        /// <summary>
        /// A namespace used only for runtime-supplied role identities does not require generated model types.
        /// Namespaces used by other node metadata retain ordinary dependency validation.
        /// </summary>
        private static bool IsRuntimeRoleNamespace(UANodeSet nodeSet, string namespaceUri)
        {
            int index = Array.IndexOf(nodeSet.NamespaceUris ?? [], namespaceUri) + 1;
            if (index == 0)
            {
                return false;
            }
            bool hasRole = false;
            string browsePrefix = index.ToString(CultureInfo.InvariantCulture) + ":";
            foreach (UANode node in nodeSet.Items ?? [])
            {
                hasRole |= (node.RolePermissions ?? []).Any(permission => UsesNamespace(permission.Value));
                if (UsesNamespace(node.NodeId) ||
                    node.BrowseName?.StartsWith(browsePrefix, StringComparison.Ordinal) == true ||
                    (node.References ?? []).Any(reference =>
                        UsesNamespace(reference.ReferenceType) || UsesNamespace(reference.Value)) ||
                    (node.Extensions ?? []).Any(XmlUsesNamespace))
                {
                    return false;
                }
                if (node is UAInstance instance && UsesNamespace(instance.ParentNodeId))
                {
                    return false;
                }
                if (node is UAMethod method && UsesNamespace(method.MethodDeclarationId))
                {
                    return false;
                }
                if (node is UAVariable variable &&
                    (UsesNamespace(variable.DataType) || XmlUsesNamespace(variable.Value)))
                {
                    return false;
                }
                if (node is UAVariableType variableType &&
                    (UsesNamespace(variableType.DataType) || XmlUsesNamespace(variableType.Value)))
                {
                    return false;
                }
                if (node is UADataType { Definition: { } definition } &&
                    (UsesNamespace(definition.BaseType) ||
                        definition.Name?.StartsWith(browsePrefix, StringComparison.Ordinal) == true ||
                        (definition.Field ?? []).Any(field => UsesNamespace(field.DataType))))
                {
                    return false;
                }
            }
            return hasRole;

            bool UsesNamespace(string? text)
            {
                if (string.IsNullOrEmpty(text))
                {
                    return false;
                }
                text = nodeSet.Aliases?.FirstOrDefault(alias => alias.Alias == text)?.Value ?? text;
                return ExpandedNodeId.TryParse(text, out ExpandedNodeId nodeId) &&
                    (nodeId.NamespaceUri == namespaceUri ||
                        (string.IsNullOrEmpty(nodeId.NamespaceUri) && nodeId.NamespaceIndex == index));
            }

            bool XmlUsesNamespace(SystemXmlElement? element)
            {
                if (element == null)
                {
                    return false;
                }
                if (UsesNamespace(element.InnerText) ||
                    (element.LocalName == "NamespaceIndex" &&
                        element.InnerText == index.ToString(CultureInfo.InvariantCulture)))
                {
                    return true;
                }
                foreach (XmlNode child in element.ChildNodes)
                {
                    if (child is SystemXmlElement childElement && XmlUsesNamespace(childElement))
                    {
                        return true;
                    }
                }
                return false;
            }
        }

        /// <summary>
        /// Compares two NodeSets of the same model URI with
        /// <see cref="SemVer.CompareModels"/>: the ModelVersion (item metadata
        /// Version overrides the declared one) with SemVer precedence, then the
        /// publication date, then the declared Version as a last heuristic. The
        /// comparison must be a total order, because the newest of several
        /// inputs is picked by pairwise replacement.
        /// </summary>
        private static int CompareVersions(NodesetFile left, NodesetFile right)
        {
            // OPC 10000-6 F.2 Table F.1: ModelVersion, then PublicationDate;
            // the Version attribute only as a last heuristic.
            return SemVer.CompareModels(
                left.ModelVersion!,
                GetPublicationDate(left),
                (GetModel(left)?.Version)!,
                right.ModelVersion!,
                GetPublicationDate(right),
                (GetModel(right)?.Version)!);
        }

        private static ModelTableEntry? GetModel(NodesetFile nodeset)
        {
            ModelTableEntry[]? models = nodeset.NodeSet?.Models;
            return models != null && models.Length > 0 ? models[0] : null;
        }

        /// <summary>
        /// The first of the candidates that carries a value.
        /// </summary>
        private static string FirstNonEmpty(params string?[] candidates)
        {
            foreach (string? candidate in candidates)
            {
                if (!string.IsNullOrEmpty(candidate))
                {
                    return candidate;
                }
            }
            return string.Empty;
        }

        private static DateTime GetPublicationDate(NodesetFile nodeset)
        {
            ModelTableEntry[]? models = nodeset.NodeSet?.Models;
            return models != null && models.Length > 0
                ? models[0].PublicationDate
                : DateTime.MinValue;
        }

        private static string GetNameFromUri(string uri)
        {
            var builder = new Uri(uri);
            string path = builder.LocalPath.TrimEnd('/');

            if (path.StartsWith("/UA/", StringComparison.OrdinalIgnoreCase))
            {
                path = path[4..];
            }

            if (path.StartsWith("/OpcUa/", StringComparison.OrdinalIgnoreCase))
            {
                path = path[7..];
            }

            path = path.Trim('/')
                .Replace("/", string.Empty, StringComparison.Ordinal)
                .Replace('-', '_')
                .Replace('+', '_');

            int colon = path.LastIndexOf(':');
            if (colon != -1)
            {
                path = path[(colon + 1)..];
            }

            if (string.IsNullOrEmpty(path))
            {
                // "http://example.com/" has no path to name the model after.
                path = builder.IsAbsoluteUri ? builder.Host : string.Empty;
            }

            // Control characters became '_' on Windows (invalid file name
            // characters) and must keep doing so everywhere; every other
            // character an identifier cannot hold is repaired by the callers.
            return new string([.. path.Select(c => char.IsControl(c) ? '_' : c)]);
        }

        /// <summary>
        /// The default <c>Namespaces</c> constant name for a model URI: a single
        /// C# identifier. A name that already is one is returned unchanged;
        /// anything else (a leading digit as in "2013/01/ISA95", a '.', or any
        /// other character an identifier cannot hold) is repaired. The repair is
        /// the same on every OS - it used to depend on the platform's invalid
        /// file name characters.
        /// </summary>
        internal static string GetDefaultNameFromUri(string uri)
        {
            string name = GetNameFromUri(uri);
            return string.IsNullOrEmpty(name) ? name : ToKeywordSafeIdentifier(name);
        }

        /// <summary>
        /// A C# identifier that needs no '@' escape. The Name and Prefix are
        /// also used in generated member names ("Add{Prefix}"), Roslyn hint
        /// names and as XML namespace prefix, where the '@' that escapes a
        /// keyword ("@class") is not allowed - a keyword gets a trailing '_'
        /// ("class_") instead. Every other identifier is returned unchanged.
        /// </summary>
        private static string ToKeywordSafeIdentifier(string name)
        {
            string identifier = name.ToCSharpIdentifierPreserveCase();
            return identifier.Length > 0 && identifier[0] == '@'
                ? identifier[1..] + "_"
                : identifier;
        }

        /// <summary>
        /// The default C# namespace (prefix) for a model URI: dot separated C#
        /// identifiers. Every segment that already is an identifier is kept
        /// unchanged, so a prefix that compiled before is not renamed.
        /// </summary>
        internal static string GetDefaultPrefixFromUri(string uri)
        {
            string name = GetNameFromUri(uri);
            if (string.IsNullOrEmpty(name))
            {
                return name;
            }
            return string.Join(
                ".",
                name.Split(['.'], StringSplitOptions.RemoveEmptyEntries)
                    .Select(ToKeywordSafeIdentifier));
        }

        private readonly ILogger m_logger;
        private readonly Dictionary<string, NodesetFile> m_nodesets = [];

        /// <summary>
        /// Every input recognised as a NodeSet2 file, whether or not it loaded
        /// and whether or not it won its model URI. See <see cref="AllFilePaths"/>.
        /// </summary>
        private readonly HashSet<string> m_nodesetPaths = new(StringComparer.Ordinal);
        private readonly List<(NodesetFile NodeSet, string IdentifierFile)> m_identifierFiles = [];
        private readonly List<NodesetIdentifierValidationError> m_identifierValidationErrors = [];
    }
}