feat(ProForma): register ProForma as a SequenceConversion format

mzLib gained a universal sequence-conversion framework in #1035
(Omics/SequenceConversion: Parser -> CanonicalSequence -> Serializer, with
pluggable IModificationLookup). ProForma was built alongside it rather than
inside it. This plugs Layer 2 into that framework instead of standing beside it.

Adds, in Readers (which is where the TopDownProteomics SDK is referenced; Omics
does not reference it):

- ProFormaSequenceFormatSchema - describes the format to the service.
- ProFormaSequenceParser  - ProForma string -> CanonicalSequence.
- ProFormaSequenceSerializer - CanonicalSequence -> ProForma string.
- ProFormaSequenceConversion.RegisterWith(service) - explicit, idempotent
  registration. Deliberately NOT a module initializer: touching
  SequenceConversionService.Default constructs GlobalModificationLookup and loads
  the modification databases, and that cost belongs to callers who convert
  sequences, not to every consumer of Readers.

Both delegate their string handling to Layer 1 (ProFormaReader/ProFormaWriter),
and the serializer emits descriptors through the existing
ProFormaConverter.BuildDescriptor (now internal), so ProForma emission has one
implementation, not two.

The payoff is interop for free: mzLib -> ProForma now converts a tool-specific
name to a community accession ("PEPC[Common Fixed:Carbamidomethyl on C]TIDE" ->
"PEPC[UNIMOD:4]TIDE") through Nic's mzLib parser and our serializer, with no
bespoke converter. It also gives the framework a parser for the accession
notation its UnimodSequenceSerializer already emits.

The flat-subset boundary is explicit and fails loud. CanonicalSequence is a flat
model - one mod per position, no groups, ranges, or delocalization - so tag
groups, position ranges, unlocalized, labile, and global mods, and sequence
ambiguity are reported as IncompatibleModifications rather than silently dropped.
Layer 1 still round-trips all of them losslessly; that is why Layer 1 keeps its
own richer AST and is not routed through the canonical IR.

Layer 2's resolution logic is intentionally left in place rather than replaced by
ModificationLookupBase: ProFormaConverter resolves accessions through an exact
index and understands context-bearing motifs (the N-glycosylation sequon "Nxs"),
whereas ModificationLookupBase.FilterByUnimodId matches accession ids by
substring Contains and FilterByMotif compares the whole motif string. Those look
like precision gaps worth raising upstream, not behavior to adopt.

Tests: 16 new (ProFormaSequenceConversionTests) covering registration, accession
and terminal and mass tags, mzLib->ProForma and ProForma round trips, the five
unrepresentable constructs, handling modes, and CanParse not stealing mzLib's own
syntax during auto-detection. Full mzLib suite green: 5177 passed / 0 failed
(baseline 5161; +16 = exactly the new tests).

Author: trishorts

mzLib/Readers/ProForma/ProFormaConverter.cs

@@ -139,7 +139,7 @@ public static Tdp.ProFormaTerm ToProFormaTerm(string baseSequence,
         /// Emits an accession (Identifier) descriptor like <c>[UNIMOD:35]</c> when the modification
         /// carries a recognized ontology reference, otherwise a Name descriptor like <c>[Oxidation]</c>.
         /// </summary>
-        private static Tdp.ProFormaDescriptor BuildDescriptor(Modification mod)
+        internal static Tdp.ProFormaDescriptor BuildDescriptor(Modification mod)
         {
             if (mod.DatabaseReference != null)
             {

mzLib/Readers/ProForma/SequenceConversion/ProFormaSequenceConversion.cs

@@ -0,0 +1,66 @@
+using Omics.SequenceConversion;
+
+namespace Readers.ProForma
+{
+    /// <summary>
+    /// Registers ProForma 2.0 as a source and target format with a
+    /// <see cref="SequenceConversionService"/>.
+    /// <para>
+    /// ProForma lives in <c>Readers</c> rather than <c>Omics</c> because it needs the
+    /// TopDownProteomics SDK, which <c>Omics</c> does not reference; registration is therefore done at
+    /// runtime, which <see cref="SequenceConversionService"/> supports by design. It is deliberately
+    /// explicit rather than a module initializer: touching
+    /// <see cref="SequenceConversionService.Default"/> loads the modification databases, and that cost
+    /// should be paid by callers who convert sequences, not by every consumer of <c>Readers</c>.
+    /// </para>
+    /// <example>
+    /// <code>
+    /// ProFormaSequenceConversion.RegisterWithDefault();
+    /// var proForma = SequenceConversionService.Default.Convert(
+    ///     "PEP[Oxidation on M]TIDE", sourceFormat: "mzLib", targetFormat: "ProForma");
+    /// </code>
+    /// </example>
+    /// </summary>
+    public static class ProFormaSequenceConversion
+    {
+        private static readonly object RegistrationLock = new();
+        private static bool _registeredWithDefault;
+
+        /// <summary>
+        /// Registers the ProForma parser, serializer, and the converters that pair ProForma with the
+        /// formats already present on <paramref name="service"/>.
+        /// </summary>
+        public static void RegisterWith(SequenceConversionService service)
+        {
+            ArgumentNullException.ThrowIfNull(service);
+
+            service.RegisterParser(ProFormaSequenceParser.Instance);
+            service.RegisterSerializer(ProFormaSequenceSerializer.Instance);
+
+            // ProForma -> ProForma is the canonicalizing round trip; the cross-format pairs let the
+            // service convert without synthesizing a converter on demand.
+            service.RegisterConverter(new SequenceConverter(ProFormaSequenceParser.Instance, ProFormaSequenceSerializer.Instance));
+            service.RegisterConverter(new SequenceConverter(MzLibSequenceParser.Instance, ProFormaSequenceSerializer.Instance));
+            service.RegisterConverter(new SequenceConverter(ProFormaSequenceParser.Instance, MzLibSequenceSerializer.Instance));
+        }
+
+        /// <summary>
+        /// Registers ProForma with <see cref="SequenceConversionService.Default"/>. Idempotent, so it
+        /// is safe to call from every entry point that needs ProForma conversion.
+        /// </summary>
+        public static void RegisterWithDefault()
+        {
+            if (_registeredWithDefault)
+                return;
+
+            lock (RegistrationLock)
+            {
+                if (_registeredWithDefault)
+                    return;
+
+                RegisterWith(SequenceConversionService.Default);
+                _registeredWithDefault = true;
+            }
+        }
+    }
+}

mzLib/Readers/ProForma/SequenceConversion/ProFormaSequenceFormatSchema.cs

@@ -0,0 +1,31 @@
+using Omics.SequenceConversion;
+
+namespace Readers.ProForma
+{
+    /// <summary>
+    /// Syntax description of HUPO-PSI ProForma 2.0 for the <see cref="SequenceConversionService"/>.
+    /// <para>
+    /// ProForma is not a bracket-tokenizable format in the sense the <c>SequenceParserBase</c> /
+    /// <c>SequenceSerializerBase</c> helpers assume, so the ProForma parser and serializer implement
+    /// <see cref="ISequenceParser"/> / <see cref="ISequenceSerializer"/> directly and delegate the
+    /// string handling to Layer 1 (the TopDownProteomics reference parser/writer). This schema is
+    /// therefore descriptive — it tells the framework what ProForma looks like; it is not the thing
+    /// that parses it.
+    /// </para>
+    /// </summary>
+    public sealed class ProFormaSequenceFormatSchema : SequenceFormatSchema
+    {
+        /// <summary>The format key this schema registers under.</summary>
+        public const string ProFormaFormatName = "ProForma";
+
+        public static ProFormaSequenceFormatSchema Instance { get; } = new();
+
+        private ProFormaSequenceFormatSchema()
+            : base(modOpen: '[', modClosed: ']', nTermSeparator: "-", cTermSeparator: "-")
+        {
+        }
+
+        /// <inheritdoc />
+        public override string FormatName => ProFormaFormatName;
+    }
+}

mzLib/Readers/ProForma/SequenceConversion/ProFormaSequenceParser.cs

@@ -0,0 +1,242 @@
+using System.Globalization;
+using Omics.SequenceConversion;
+using Tdp = TopDownProteomics.ProForma;
+
+namespace Readers.ProForma
+{
+    /// <summary>
+    /// Parses a ProForma 2.0 string into a <see cref="CanonicalSequence"/>, making ProForma a
+    /// first-class source format for <see cref="SequenceConversionService"/>.
+    /// <para>
+    /// The string handling is delegated to Layer 1 (<see cref="ProFormaReader"/>), which is lossless.
+    /// The lossy step is Layer 1 -&gt; canonical: <see cref="CanonicalSequence"/> is a flat model
+    /// (one modification per position, no groups/ranges/delocalization), so ProForma constructs that
+    /// cannot be expressed in it — tag groups, position ranges, unlocalized, labile, and global
+    /// modifications, and sequence ambiguity — are reported as incompatible rather than silently
+    /// dropped. Use Layer 1 directly when losslessness matters.
+    /// </para>
+    /// </summary>
+    public sealed class ProFormaSequenceParser : ISequenceParser
+    {
+        public static ProFormaSequenceParser Instance { get; } = new();
+
+        private ProFormaSequenceParser() { }
+
+        /// <inheritdoc />
+        public string FormatName => ProFormaSequenceFormatSchema.ProFormaFormatName;
+
+        /// <inheritdoc />
+        public SequenceFormatSchema Schema => ProFormaSequenceFormatSchema.Instance;
+
+        /// <summary>
+        /// Fast heuristic used by <c>ParseAutoDetect</c>. Deliberately conservative: a bare sequence
+        /// and mzLib's own <c>"[Type:Name on X]"</c> syntax are both left to the mzLib parser, so this
+        /// only claims strings carrying a ProForma-distinctive token that also parse and fit the flat
+        /// canonical model.
+        /// </summary>
+        public bool CanParse(string input)
+        {
+            if (string.IsNullOrWhiteSpace(input) || !LooksLikeProForma(input))
+                return false;
+
+            try
+            {
+                return DescribeUnrepresentable(ProFormaReader.Read(input)) is null;
+            }
+            catch (Tdp.ProFormaParseException)
+            {
+                return false;
+            }
+        }
+
+        /// <inheritdoc />
+        public CanonicalSequence? Parse(
+            string input,
+            ConversionWarnings? warnings = null,
+            SequenceConversionHandlingMode mode = SequenceConversionHandlingMode.ThrowException)
+        {
+            warnings ??= new ConversionWarnings();
+
+            if (string.IsNullOrWhiteSpace(input))
+            {
+                return SequenceConversionHelpers.HandleParserError(warnings, mode,
+                    ConversionFailureReason.InvalidSequence, "ProForma input is null or empty.");
+            }
+
+            Tdp.ProFormaTerm term;
+            try
+            {
+                term = ProFormaReader.Read(input);
+            }
+            catch (Tdp.ProFormaParseException ex)
+            {
+                return SequenceConversionHelpers.HandleParserError(warnings, mode,
+                    ConversionFailureReason.InvalidSequence,
+                    $"'{input}' is not valid ProForma 2.0: {ex.Message}");
+            }
+
+            var unrepresentable = DescribeUnrepresentable(term);
+            if (unrepresentable is not null)
+            {
+                warnings.AddIncompatibleItem(unrepresentable);
+                return SequenceConversionHelpers.HandleParserError(warnings, mode,
+                    ConversionFailureReason.IncompatibleModifications,
+                    $"ProForma term '{input}' cannot be represented as a CanonicalSequence: {unrepresentable}. " +
+                    "Use the ProForma reader (Layer 1) directly to work with this term losslessly.");
+            }
+
+            var builder = new CanonicalSequenceBuilder(term.Sequence)
+                .WithSourceFormat(FormatName);
+
+            if (term.NTerminalDescriptors is { Count: > 0 })
+            {
+                var (representation, unimodId, mass) = Describe(term.NTerminalDescriptors, warnings, term);
+                builder.AddNTerminalModification(representation, mass, formula: null, unimodId: unimodId);
+            }
+
+            if (term.Tags is not null)
+            {
+                foreach (var tag in term.Tags)
+                {
+                    var (representation, unimodId, mass) = Describe(tag.Descriptors, warnings, term);
+                    builder.AddResidueModification(tag.ZeroBasedStartIndex, representation, mass,
+                        formula: null, unimodId: unimodId);
+                }
+            }
+
+            if (term.CTerminalDescriptors is { Count: > 0 })
+            {
+                var (representation, unimodId, mass) = Describe(term.CTerminalDescriptors, warnings, term);
+                builder.AddCTerminalModification(representation, mass, formula: null, unimodId: unimodId);
+            }
+
+            // The flat model allows only one modification per position; ProForma does not.
+            var errors = builder.Validate();
+            if (errors.Count > 0)
+            {
+                foreach (var error in errors)
+                    warnings.AddIncompatibleItem(error);
+
+                return SequenceConversionHelpers.HandleParserError(warnings, mode,
+                    ConversionFailureReason.IncompatibleModifications,
+                    $"ProForma term '{input}' does not fit the canonical model: {string.Join(" ", errors)}");
+            }
+
+            return builder.Build();
+        }
+
+        /// <summary>
+        /// Names the first ProForma construct in <paramref name="term"/> that the flat
+        /// <see cref="CanonicalSequence"/> model cannot hold, or null when the term is representable.
+        /// This is the Layer-1 → canonical boundary, stated explicitly so callers fail loud.
+        /// </summary>
+        internal static string? DescribeUnrepresentable(Tdp.ProFormaTerm term)
+        {
+            if (term.TagGroups is { Count: > 0 })
+                return "tag groups (crosslinks / localization groups)";
+            if (term.LabileDescriptors is { Count: > 0 })
+                return "labile modifications";
+            if (term.UnlocalizedTags is { Count: > 0 })
+                return "unlocalized modifications";
+            if (term.GlobalModifications is { Count: > 0 })
+                return "global modifications";
+
+            if (term.Tags is not null)
+            {
+                foreach (var tag in term.Tags)
+                {
+                    if (tag.ZeroBasedStartIndex != tag.ZeroBasedEndIndex)
+                        return "position ranges";
+                    if (tag.HasAmbiguousSequence)
+                        return "sequence ambiguity";
+                }
+            }
+
+            return null;
+        }
+
+        /// <summary>
+        /// Collapses a ProForma descriptor list onto the single representation a
+        /// <see cref="CanonicalModification"/> can hold, preferring an ontology accession (most
+        /// resolvable) over a name over a mass. ProForma permits several descriptors on one tag
+        /// (e.g. <c>[Phospho|UNIMOD:21]</c>); the canonical model does not, so the surplus is
+        /// reported as a warning — the information is still intact in the Layer-1 term.
+        /// </summary>
+        private static (string Representation, int? UnimodId, double? Mass) Describe(
+            IList<Tdp.ProFormaDescriptor> descriptors, ConversionWarnings warnings, Tdp.ProFormaTerm term)
+        {
+            Tdp.ProFormaDescriptor? preferred = null;
+            int? unimodId = null;
+            double? mass = null;
+
+            foreach (var descriptor in descriptors)
+            {
+                if (descriptor.Key == Tdp.ProFormaKey.Identifier)
+                {
+                    preferred ??= descriptor;
+                    unimodId ??= TryGetUnimodId(descriptor.Value);
+                }
+                else if (descriptor.Key == Tdp.ProFormaKey.Mass
+                         && double.TryParse(descriptor.Value, NumberStyles.Float, CultureInfo.InvariantCulture, out var parsed))
+                {
+                    mass ??= parsed;
+                }
+            }
+
+            preferred ??= descriptors.FirstOrDefault(d => d.Key == Tdp.ProFormaKey.Name)
+                          ?? descriptors.FirstOrDefault();
+
+            if (descriptors.Count > 1)
+            {
+                warnings.AddWarning(
+                    $"ProForma tag [{string.Join("|", descriptors.Select(d => d.Value))}] in '{term.Sequence}' carries " +
+                    $"{descriptors.Count} descriptors; the canonical model keeps one ('{preferred?.Value}').");
+            }
+
+            return (preferred?.Value ?? string.Empty, unimodId, mass);
+        }
+
+        /// <summary>Extracts 35 from "UNIMOD:35". Returns null for any other ontology.</summary>
+        private static int? TryGetUnimodId(string? value)
+        {
+            const string prefix = "UNIMOD:";
+            if (value is null || !value.StartsWith(prefix, StringComparison.OrdinalIgnoreCase))
+                return null;
+
+            return int.TryParse(value.AsSpan(prefix.Length), NumberStyles.Integer, CultureInfo.InvariantCulture, out var id)
+                ? id
+                : null;
+        }
+
+        /// <summary>
+        /// True when the string carries a token only ProForma uses. Keeps auto-detection from
+        /// claiming plain sequences or mzLib's "Name on X" motif syntax.
+        /// </summary>
+        private static bool LooksLikeProForma(string input)
+        {
+            if (input.Contains(" on ", StringComparison.OrdinalIgnoreCase))
+                return false;
+
+            if (input.IndexOfAny(['{', '<', '#']) >= 0)
+                return true;
+
+            foreach (var ontology in Ontologies)
+            {
+                if (input.Contains(ontology, StringComparison.OrdinalIgnoreCase))
+                    return true;
+            }
+
+            // A bare mass tag, e.g. PEP[+15.9949]TIDE.
+            for (int i = 0; i < input.Length - 2; i++)
+            {
+                if (input[i] == '[' && (input[i + 1] == '+' || input[i + 1] == '-') && char.IsDigit(input[i + 2]))
+                    return true;
+            }
+
+            return false;
+        }
+
+        private static readonly string[] Ontologies =
+            ["UNIMOD:", "MOD:", "RESID:", "XLMOD:", "GNO:", "Obs:", "Info:", "Formula:", "Glycan:"];
+    }
+}