Semantic member metadata, and the editor controls that set it

[matt-edmondson]

Three pieces of work, plus two follow-ups from the quality gate: the model and file format for the metadata a member carries beside its type, the editor surface that lets a person set it, and the generated C# that carries it out to a consumer and back.

1. Give a member a unit, a range, a default, and how to send it

A member could say what type it was and nothing about what it meant. This adds the semantic layer: Unit, Range, DefaultValue, Interpolation, Network and Editor, as direct properties on SchemaMember and on ISchemaMember. All six are optional and omitted when absent.

Units come from ktsu.Semantics.Quantities

A member stores the text — a symbol ("m/s") or a unit name ("MeterPerSecond") — and UnitRegistry resolves it against the 189 units in that package, so conversion factors and dimensional formulae stay owned by the library that generates them instead of being copied into every schema file. The registry is built by reflecting over the quantities assembly rather than being a list maintained here, which would fall behind every unit added upstream.

Symbols are not unique, and the two collisions are not harmless: g is both gram and standard gravity, and rad is both radian and radiation absorbed dose — not even the same dimension. Resolution refuses an ambiguous symbol and names the candidates rather than picking one; writing the unit's name is how a schema escapes it.

Name lookup is StringComparer.Ordinal, not OrdinalIgnoreCase: with case-insensitivity "rad" matched the name Rad before the symbol check ran and silently resolved to an absorbed radiation dose instead of reporting the ambiguity.

Validation

Checks what only makes sense in combination: a unit on something that measures nothing, a backwards range, a default outside its range or of the wrong kind, an enum default naming a value the enum does not have, interpolation on something with no meaningful midpoint, a negative quantisation step. A quantisation step wider than the whole range is a warning rather than an error — suspicious, not invalid.

wrap is the case that is easy to get backwards, so it is stated explicitly in the docs and asserted in the tests: a wrapping range is a period, not a bound. Seven radians on a [0, 2π) member is un-normalised rather than wrong, and clamping it to the maximum is the one transformation that is certainly incorrect. A default outside a wrapping range is therefore accepted.

formatVersion moves to 2

Purely additive — a file using none of the new properties is byte-identical to the version 1 file it would have been — but a version 1 reader ignores properties it does not recognise, so it would load such a file, drop the metadata and write it back without it. That is exactly the information loss the round-trip contract in docs/schema-format.md forbids, so refusing to read it is the honest outcome.

Three defects found by looking at the emitted JSON

A round trip passes happily on all three, so a test now asserts the emitted JSON directly.

• IsWellFormed and IsQuantised were being written to the file. A derived property in a file is a second, independently editable copy of a fact the file already states. Now [JsonIgnore].
• Interpolation was written as an ordinal, so inserting a mode into the enum would have silently changed the meaning of every existing schema. It is written by name now.
• The docs said the default discriminator was defaultKind; it is DefaultKind, matching the existing TypeName discriminator.

2. Let the editor set a member's unit, range, default and encoding

The metadata existed in the model and in the file, and nowhere a person could reach it: the editor drew a member's name, type, container and key, and none of the six.

Each member row now has a second fold beside the description one, holding a unit picker, the range and its wrap flag, the default and its kind, the interpolation mode, the network encoding and the editor hint. Folded away rather than in the row, because the row is already five controls wide and all six are absent on most members — an identifier measures nothing and blends with nothing. The fold's own button says whether there is anything behind it, since a folded row is the only place most members are ever seen.

• The unit picker is the registry, searchable by name or symbol. What it writes is UnitRegistry.PreferredText: the symbol when the symbol names one unit, the name when it does not. A picker knows which unit was chosen, so writing "rad" for a radian — text the resolver then refuses as ambiguous — would throw that away. A test asserts the round trip over every unit in the registry rather than a sample.
• An enum member's default is offered as that enum's values rather than as free text. It is the mistake the property invites, and the schema already knows which names are allowed.
• Numbers go through a new EditField.Number, for the reason the rest of that class exists: ImGui's own numeric input reports its value every frame, so a bound edited through it would push an undo entry per keystroke. Text also holds what a number cannot (-, 0., an empty box) without the model seeing any of it, and unparsable text leaves the bound alone. Every edit here is one undo entry, and a range and an encoding are immutable, so each edit replaces one rather than mutating it.

3. Carry the metadata through generated C# and back

Generated code said a member was a float and nothing about what the float meant, so a consumer reading the generated types got none of this, and reimporting them gave back a schema missing everything it started with.

Generated properties now carry SchemaUnit, SchemaRange, SchemaDefault, SchemaInterpolation, SchemaNetwork and SchemaEditorHint from ktsu.Schema.Runtime, and the importer reads them back. This is what SchemaKeyAttribute already did for a keyed map's key member, for the same reason: a CLR type cannot say it, so without the attribute the round trip loses it. The existing generate-compile-reimport test now compares all six, so neither side can change alone.

[ktsu.Schema.Runtime.SchemaUnit("m/s")]
[ktsu.Schema.Runtime.SchemaRange(0D, 6.2831853D, Wrap = true)]
[ktsu.Schema.Runtime.SchemaDefault(1.5D)]
[ktsu.Schema.Runtime.SchemaEditorHint("dial")]
public float Ratio { get; set; } = 1.5f;

SchemaDefault is one attribute with a constructor per kind of value rather than three attributes, because a member has one default: the overload the generator picks says which kind it is, and the boxed value is what still remembers on the way back. A default is also emitted as the property's initialiser, so a generated instance starts at the default instead of merely recording what it should have been — the initialiser makes the object right, the attribute makes the default readable off the type. A default of a kind the member cannot hold is a validation error and generation refuses an invalid schema, but the generator is public, so a mismatch falls through to the type's own initialiser rather than emitting source that does not compile; there is a test for that path.

Floating point, twice, from the quality gate

The last two commits answer SonarCloud and the code-quality bot, which found three exact floating-point comparisons in the new code. Both bots proposed tolerances; none was taken, because in each case a tolerance changes what the check means.

• Is a default a whole number. The member is integral, so the default has to survive narrowing to an int; accepting 1.0000000001 as whole means accepting a value that then silently becomes 1 — the loss the check exists to catch. It reads !double.IsInteger(number.Value) now, which asks the question directly. One deliberate consequence: an infinite default on an integral member is now reported, because Math.Truncate(double.PositiveInfinity) returns the infinity and the old comparison called it whole.
• Is a wrapping range zero-width. Math.Abs(min - max) <= double.Epsilon is not a tolerance — double.Epsilon is the smallest denormal — it is equality that reads as though it forgives imprecision. The check now runs after the well-formed check, which lets it read Maximum <= Minimum: the range satisfies min <= max by then, so that states equality without comparing two doubles.
• Has the number in a field changed. The field is bound to text, so it is answered as text: render the parsed value and compare the strings. "1.0" and "1" still count as the same number.

Each has a test for the edge it decides.

Three extractions, no behaviour change

SchemaEditor and Schema were each one type below CA1506's coupling limit, so each of these was needed to add anything at all, and each is the pattern the repository already uses (CodeGeneratorPanel):

• MemberGridPanel — the member grid, out of SchemaEditor.
• MemberSemanticsPanel — the metadata fold.
• ClrTypeImporter — the reflection importer, out of Schema. Schema.AddClass(Type) is unchanged and delegates to it.

No probe name changed, so the existing editor tests moved with the grid untouched.

Testing

49 new tests. In Release on net10.0: 334 pass in Schema.Test and 201 pass in SchemaEditor.Test, none failing or skipped. The editor tests drive the real editor headlessly, because an immediate-mode control's value only reaches the schema through what the widget reports. Schema also targets net9.0 and net8.0 — both compile, and CI runs all of them on Ubuntu and Windows.

The remaining Sonar findings on the branch are assertion-style preferences from a newer MSTest analyzer (Assert.IsEmpty over Assert.AreEqual(0, …), and so on). They are maintainability rather than reliability, the gate does not fail on them, and the rest of this suite does not follow that style either — converting only the new tests would leave the suite inconsistent with itself.

docs/schema-format.md, README.md and CLAUDE.md are updated.

🤖 Generated with Claude Code

https://claude.ai/code/session_01NmGpVzuXro25PVp3e1CRru

[sonarqubecloud]

Quality Gate passed

Issues
20 New issues
0 Accepted issues

Measures
0 Security Hotspots
92.9% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud