Fix #296

Author: antoineatstariongroup

SysML2.NET.CodeGenerator/Extensions/GrammarErrata.cs

@@ -25,25 +25,30 @@ namespace SysML2.NET.CodeGenerator.Extensions
     using System.Linq;
 
     /// <summary>
-    /// Supplies the target metaclass for KEBNF rules whose name does not match the metaclass they build,
-    /// at generation time.
+    /// Corrects known defects in the KEBNF grammar carried under <c>Resources/</c>, at generation time.
     /// </summary>
     /// <remarks>
-    /// The KEBNF files under <c>Resources/</c> are OMG source and are never edited, and the generated
-    /// output is never hand-edited either — so a rule that omits a target the generator cannot infer can
-    /// only be corrected here, on the way from the one to the other. The files reproduce the
-    /// textual-notation BNF of the KerML and SysML specifications verbatim, so a defect here is a
-    /// SPECIFICATION defect; OMG has confirmed this class of finding and routes the fix through the
-    /// Revision Task Forces (Systems-Modeling/SysML-v2-Release issue 124).
-    /// <para>The grammar writes an explicit target whenever the rule name differs from the metaclass
-    /// (<c>RequirementKind : RequirementConstraintMembership</c>, <c>SubjectMember : SubjectMembership</c>).
-    /// Every entry below is a rule where that annotation is missing, so the rule name resolves to no
-    /// metaclass at all and the generator falls back to inferring one from the assigned property names —
-    /// which silently selects an unrelated class that happens to declare the same property.</para>
-    /// <para>Scope is deliberately narrow: an entry corrects a rule the generator would otherwise bind to
-    /// the WRONG metaclass. A production that merely admits more than one valid spelling is NOT an
-    /// erratum — choosing between admissible spellings is the writer's business, not a correction to the
-    /// grammar.</para>
+    /// The KEBNF files are OMG source and are never edited, and the generated output is never hand-edited
+    /// either — so a defect can only be corrected here, on the way from the one to the other. The files are
+    /// mechanically extracted from the specification document, while the pilot implementation's parser is a
+    /// separately hand-maintained Xtext grammar; the two drift, and a defect here is a SPECIFICATION defect.
+    /// OMG has confirmed this class of finding and routes the fix through the Revision Task Forces
+    /// (Systems-Modeling/SysML-v2-Release issue 124).
+    /// <para>Two kinds of correction, because the defects differ in kind:</para>
+    /// <para><see cref="Entries" /> — a rule whose name does not match the metaclass it builds and which
+    /// omits the explicit target the grammar normally writes in that case
+    /// (<c>RequirementKind : RequirementConstraintMembership</c>). Without it the rule name resolves to no
+    /// metaclass, and the generator falls back to inferring one from the assigned property names, silently
+    /// selecting an unrelated class that happens to declare the same property.</para>
+    /// <para><see cref="ProductionEntries" /> — a production whose token sequence cannot derive notation the
+    /// metamodel and the specification's own normative examples require. Applied to the grammar TEXT before
+    /// it is parsed, so the corrected production flows through the normal pipeline and nothing downstream
+    /// needs to special-case the rule.</para>
+    /// <para>Scope is deliberately narrow, and the bar for both kinds is the same: the generator would
+    /// otherwise produce output that is WRONG, not merely different. A production that admits more than one
+    /// valid spelling is NOT an erratum — choosing between admissible spellings is the writer's business.
+    /// The reference test is whether the pilot's Xtext grammar accepts what we emit: where it does, any
+    /// difference is a style choice; where it cannot, the grammar is genuinely deficient.</para>
     /// <para>These corrections are expected to become unnecessary as OMG publishes fixes. On a new KEBNF
     /// release, run the generator and prune whatever <see cref="QueryUnappliedErrata" /> reports — an entry
     /// that no longer matches has been fixed upstream.</para>
@@ -59,6 +64,34 @@ public static class GrammarErrata
                 "KerML 8.2.2.24 writes 'LiteralReal = value = RealValue' with no target, but no metaclass named 'LiteralReal' exists — KerML 8.3.4.9 names it 'LiteralRational'. Its sibling literal rules (LiteralBoolean, LiteralString, LiteralInteger, LiteralInfinity) all match a metaclass by name, so only this one is left unresolved.")
         ];
 
+        /// <summary>
+        /// The production-text corrections applied to the grammar before it is parsed.
+        /// </summary>
+        /// <remarks>
+        /// An entry belongs here only when the grammar cannot derive the notation at all. A production that
+        /// merely admits a spelling we do not emit is NOT an erratum — see the class remarks.
+        /// </remarks>
+        private static readonly GrammarProductionErratum[] ProductionEntries =
+        [
+            new("CaseBodyItem",
+                "CaseBodyItem : Type =\r\n      ActionBodyItem",
+                "CaseBodyItem : Type =\r\n      CalculationBodyItem",
+                "SysML 8.2.2.22.1 gives CaseBodyItem the alternative 'ActionBodyItem', which reaches no " +
+                "ReturnParameterMember, so 'return' cannot be written in a case body. Three independent " +
+                "sources say it must be: (1) the pilot implementation's own grammar uses " +
+                "'CalculationBodyItem' here (org.omg.sysml.xtext SysML.xtext, rule CaseBodyItem), and " +
+                "CalculationBodyItem = ActionBodyItem | ReturnParameterMember; (2) the metamodel permits it " +
+                "— constraint validateReturnParameterMembershipOwningType requires the owningType of a " +
+                "ReturnParameterMembership to be a Function or Expression, and VerificationCaseUsage " +
+                "specializes CaseUsage specializes CalculationUsage specializes Expression; (3) the " +
+                "normative example in SysML 7.24.2 writes 'return verdict : VerdictKind = " +
+                "evaluateData.verdict;' inside a 'verification def' body. There is no admissible " +
+                "alternative spelling: rendering the ReturnParameterMembership through the generic " +
+                "parameter path emits 'out verdict', which re-parses as a plain FeatureMembership with " +
+                "direction out and so loses the metaclass. CalculationBodyItem is already declared in the " +
+                "same file, so the replacement resolves without any further correction.")
+        ];
+
         /// <summary>
         /// The corrections that have matched at least one rule during this generator run.
         /// </summary>
@@ -97,16 +130,57 @@ public static string ApplyTarget(string ruleName, string targetElementName)
         }
 
         /// <summary>
-        /// Returns the corrections that matched no rule during this generator run.
+        /// Applies every known production correction to the raw text of a KEBNF file.
+        /// </summary>
+        /// <param name="kebnfSource">The grammar text as read from disk.</param>
+        /// <returns>
+        /// The corrected grammar text, or <paramref name="kebnfSource" /> unchanged when nothing applies.
+        /// </returns>
+        /// <remarks>
+        /// Correcting the text rather than the parsed rule keeps the correction in the grammar's own
+        /// language: the entry reads as the production OMG should have written, and every consumer parses
+        /// it exactly as it parses the rest of the file. Each <c>Original</c> is matched verbatim, so a
+        /// correction cannot partially match, and re-applying it to already-corrected text is a no-op.
+        /// Both KEBNF files are passed through this, so an entry only fires against the file that carries
+        /// its production.
+        /// </remarks>
+        public static string ApplyProductions(string kebnfSource)
+        {
+            if (string.IsNullOrWhiteSpace(kebnfSource))
+            {
+                return kebnfSource;
+            }
+
+            return ProductionEntries
+                .Where(erratum => kebnfSource.Contains(erratum.Original, StringComparison.Ordinal))
+                .Aggregate(kebnfSource, (corrected, erratum) =>
+                {
+                    AppliedRuleNames.Add(erratum.RuleName);
+
+                    return corrected.Replace(erratum.Original, erratum.Replacement);
+                });
+        }
+
+        /// <summary>
+        /// Returns the corrections that matched nothing during this generator run.
         /// </summary>
-        /// <returns>The stale entries, which should be pruned from <see cref="Entries" />.</returns>
+        /// <returns>The stale entries, which should be pruned.</returns>
         /// <remarks>
-        /// Only meaningful once every rule has been read. A stale entry means the grammar no longer carries
-        /// the defect — either OMG annotated the rule, or the rule was renamed or removed.
+        /// Only meaningful once every grammar file has been loaded and every rule read. A stale entry means
+        /// the grammar no longer carries the defect — either OMG corrected it, or the rule was renamed or
+        /// removed.
         /// </remarks>
-        public static IReadOnlyList<GrammarErratum> QueryUnappliedErrata()
+        public static IReadOnlyList<(string RuleName, string Justification)> QueryUnappliedErrata()
         {
-            return [..Entries.Where(erratum => !AppliedRuleNames.Contains(erratum.RuleName))];
+            return
+            [
+                ..Entries
+                    .Where(erratum => !AppliedRuleNames.Contains(erratum.RuleName))
+                    .Select(erratum => (erratum.RuleName, erratum.Justification)),
+                ..ProductionEntries
+                    .Where(erratum => !AppliedRuleNames.Contains(erratum.RuleName))
+                    .Select(erratum => (erratum.RuleName, erratum.Justification))
+            ];
         }
     }
 }

SysML2.NET.CodeGenerator/Extensions/GrammarProductionErratum.cs

@@ -0,0 +1,86 @@
+// -------------------------------------------------------------------------------------------------
+// <copyright file="GrammarProductionErratum.cs" company="Starion Group S.A.">
+//
+//   Copyright 2022-2026 Starion Group S.A.
+//
+//   Licensed under the Apache License, Version 2.0 (the "License");
+//   you may not use this file except in compliance with the License.
+//   You may obtain a copy of the License at
+//
+//        http://www.apache.org/licenses/LICENSE-2.0
+//
+//    Unless required by applicable law or agreed to in writing, software
+//    distributed under the License is distributed on an "AS IS" BASIS,
+//    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+//    See the License for the specific language governing permissions and
+//    limitations under the License.
+//
+// </copyright>
+// ------------------------------------------------------------------------------------------------
+
+namespace SysML2.NET.CodeGenerator.Extensions
+{
+    using System;
+
+    /// <summary>
+    /// A single correction applied to the text of a KEBNF production before it is parsed.
+    /// </summary>
+    public sealed class GrammarProductionErratum
+    {
+        /// <summary>
+        /// Initializes a new instance of the <see cref="GrammarProductionErratum" /> class.
+        /// </summary>
+        /// <param name="ruleName">The rule the correction belongs to, used when reporting staleness.</param>
+        /// <param name="original">The exact production text the grammar carries.</param>
+        /// <param name="replacement">The text it is corrected to.</param>
+        /// <param name="justification">The evidence that the original is a defect rather than intent.</param>
+        /// <exception cref="ArgumentException">Thrown when any argument is null or whitespace.</exception>
+        public GrammarProductionErratum(string ruleName, string original, string replacement, string justification)
+        {
+            if (string.IsNullOrWhiteSpace(ruleName))
+            {
+                throw new ArgumentException("The rule name is required.", nameof(ruleName));
+            }
+
+            if (string.IsNullOrWhiteSpace(original))
+            {
+                throw new ArgumentException("The original production text is required.", nameof(original));
+            }
+
+            if (string.IsNullOrWhiteSpace(replacement))
+            {
+                throw new ArgumentException("The replacement production text is required.", nameof(replacement));
+            }
+
+            if (string.IsNullOrWhiteSpace(justification))
+            {
+                throw new ArgumentException("A justification is required so the correction can be audited.", nameof(justification));
+            }
+
+            this.RuleName = ruleName;
+            this.Original = original;
+            this.Replacement = replacement;
+            this.Justification = justification;
+        }
+
+        /// <summary>
+        /// Gets the rule the correction belongs to.
+        /// </summary>
+        public string RuleName { get; }
+
+        /// <summary>
+        /// Gets the exact production text the grammar carries.
+        /// </summary>
+        public string Original { get; }
+
+        /// <summary>
+        /// Gets the text it is corrected to.
+        /// </summary>
+        public string Replacement { get; }
+
+        /// <summary>
+        /// Gets the evidence that the original is a defect rather than intent.
+        /// </summary>
+        public string Justification { get; }
+    }
+}

SysML2.NET.CodeGenerator/Extensions/NotationInvariant.cs

@@ -0,0 +1,79 @@
+// -------------------------------------------------------------------------------------------------
+// <copyright file="NotationInvariant.cs" company="Starion Group S.A.">
+//
+//   Copyright 2022-2026 Starion Group S.A.
+//
+//   Licensed under the Apache License, Version 2.0 (the "License");
+//   you may not use this file except in compliance with the License.
+//   You may obtain a copy of the License at
+//
+//        http://www.apache.org/licenses/LICENSE-2.0
+//
+//    Unless required by applicable law or agreed to in writing, software
+//    distributed under the License is distributed on an "AS IS" BASIS,
+//    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+//    See the License for the specific language governing permissions and
+//    limitations under the License.
+//
+// </copyright>
+// ------------------------------------------------------------------------------------------------
+
+namespace SysML2.NET.CodeGenerator.Extensions
+{
+    using System;
+
+    /// <summary>
+    /// A single notation invariant: a rule the writer must honour that neither the KEBNF nor the metamodel
+    /// states machine-readably, anchored to the OMG name it depends on.
+    /// </summary>
+    public sealed class NotationInvariant
+    {
+        /// <summary>
+        /// Initializes a new instance of the <see cref="NotationInvariant" /> class.
+        /// </summary>
+        /// <param name="name">The stable key the generator refers to the invariant by.</param>
+        /// <param name="metamodelName">The OMG metaclass or property name the invariant depends on.</param>
+        /// <param name="justification">Why the invariant holds, and what breaks without it.</param>
+        /// <exception cref="ArgumentException">Thrown when any argument is null or whitespace.</exception>
+        public NotationInvariant(string name, string metamodelName, string justification)
+        {
+            if (string.IsNullOrWhiteSpace(name))
+            {
+                throw new ArgumentException("The invariant name is required.", nameof(name));
+            }
+
+            if (string.IsNullOrWhiteSpace(metamodelName))
+            {
+                throw new ArgumentException("The metamodel name is required.", nameof(metamodelName));
+            }
+
+            if (string.IsNullOrWhiteSpace(justification))
+            {
+                throw new ArgumentException("A justification is required so the invariant can be audited.", nameof(justification));
+            }
+
+            this.Name = name;
+            this.MetamodelName = metamodelName;
+            this.Justification = justification;
+        }
+
+        /// <summary>
+        /// Gets the stable key the generator refers to the invariant by.
+        /// </summary>
+        /// <remarks>
+        /// Deliberately independent of <see cref="MetamodelName" />: the generator names the CONCEPT, so an
+        /// OMG rename is a single edit here rather than a hunt through the emission code.
+        /// </remarks>
+        public string Name { get; }
+
+        /// <summary>
+        /// Gets the OMG metaclass or property name the invariant depends on.
+        /// </summary>
+        public string MetamodelName { get; }
+
+        /// <summary>
+        /// Gets the reason the invariant holds, and what breaks without it.
+        /// </summary>
+        public string Justification { get; }
+    }
+}