feat(generator): plural From{Unit} factory naming + form matrix docs (closes #49, partial #58)#72
Merged
matt-edmondson merged 1 commit intovectorsfrom May 10, 2026
Conversation
…loses #49) Issue #49 — every generated From{Unit} factory now uses the plural form, matching the convention CLAUDE.md and docs/strategy-unified-vector-quantities.md already advertise (Speed.FromMetersPerSecond, Force1D.FromNewtons, etc). - UnitDefinition gets a new optional FactoryName field. units.json sets it explicitly on every unit, including: * regular: Meter -> Meters, Newton -> Newtons, Joule -> Joules, ... * irregular: Foot -> Feet, Inch -> Inches, SquareFoot -> SquareFeet, SquareInch -> SquareInches, PoundFoot -> PoundFeet, Henry -> Henries * mass nouns / no-plural: Hertz, Lux, Siemens, Stokes, Psi, Horsepower, Celsius, Fahrenheit, Gauss, Poise, Dimensionless * already-plural compounds (Per): MetersPerSecond, KilometersPerHour, RadiansPerSecond, JoulePerKelvin, etc. all keep their name. - QuantitiesGenerator.AddUnitFactories looks up FactoryName from the unit map; falls back to Name + "s" when absent (correct for regular units, and lets dimensions.json that aren't migrated yet still build). - Regenerated Semantics.Quantities/Generated/. Spot-checked Length (FromMeters / FromKilometers / FromCentimeters / FromMillimeters / FromNanometers / FromAngstroms / FromFeet / FromInches / FromYards / FromMiles), Velocity1D (FromMetersPerSecond / FromKilometersPerHour / FromMilesPerHour), Frequency (FromHertz), Temperature (FromKelvins / FromCelsius / FromFahrenheit). All preserve the V0 non-negativity guard from #50 and the V0 - V0 absolute subtraction from #52. Updated tests in Semantics.Test/Quantities/{MultiUnitFactoryTests, Vector0InvariantTests,VectorQuantityTests,SemanticOverloadTests}.cs to use the new plural names (call sites + method names). Updated docs: - docs/physics-domains-guide.md, docs/complete-library-guide.md: example call sites switched to plural forms. - CLAUDE.md: noted the plural-naming convention and that every new unit in units.json must set factoryName. Issue #58 part 1 — added a "Form Coverage Matrix" section to docs/strategy-unified-vector-quantities.md documenting the canonical patterns (linear V0-V4, angular V0/V1/V3, scalar-only V0(+V1), etc.) and explaining that the generator silently skips a relationship form when either side is missing, so a new dimension must declare any form it needs to participate in. The SEM003 generator-time validator suggested in #58 needs a metadata schema change first (relationships are dimension-to-dimension today, not form-specific) — leaving that for a follow-up.
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Closes #49 and addresses the documentation half of #58.
#49 — plural
From{Unit}factory namingUnitDefinitiongets an optionalFactoryNamefield. Every entry inunits.jsonnow sets it explicitly:name + "s")Meter→Meters,Newton→Newtons,Joule→Joules,Kilogram→KilogramsFoot→Feet,Inch→Inches,SquareFoot→SquareFeet,PoundFoot→PoundFeet,Henry→HenriesHertz,Lux,Siemens,Stokes,Psi,Horsepower,Celsius,Fahrenheit,Gauss,Poise,DimensionlessMetersPerSecond,KilometersPerHour,RadiansPerSecond,JoulePerKelvin, … all kept as-isQuantitiesGenerator.AddUnitFactoriesreadsFactoryNamefrom the unit map and falls back toname + "s"when absent — correct for regulars and keeps unmigrated metadata building.The new factory shape now matches what
CLAUDE.mdanddocs/strategy-unified-vector-quantities.mdhave advertised all along (Speed.FromMetersPerSecond,Force1D.FromNewtons, etc.).The V0 non-negativity guard from #50 and the V0 − V0 absolute subtraction operator from #52 are unchanged — only the factory name changed, not its body or argument shape.
#58 (part 1) — form coverage matrix
Added a "Form Coverage Matrix" section to
docs/strategy-unified-vector-quantities.mdwriting down what was previously implicit:Ratio+ V1SignedRatioPlus a paragraph clarifying that the generator silently skips a relationship's form when either side doesn't declare it, so a new dimension has to declare every form it needs to participate in.
The SEM003 piece of #58 — a generator-time validator that fails fast when a relationship references a form the dimension doesn't declare — needs a metadata schema change first (current relationships are dimension-to-dimension, not form-specific). Not in this PR; comment on #58 explains.
Migration impact
Renames affect every call site of generated
From{Unit}factories. Updated in this PR:Semantics.Test/Quantities/{MultiUnitFactoryTests,Vector0InvariantTests,VectorQuantityTests,SemanticOverloadTests}.cs(call sites + method names)docs/physics-domains-guide.md,docs/complete-library-guide.md(example call sites)External consumers calling singular forms (
FromMeter,FromKilogram, etc.) will need to switch to the plural — this is a deliberate breaking change to fix the inconsistency.Test plan
dotnet build Semantics.SourceGenerators— cleandotnet build Semantics.Quantities— generator runs cleanly (no SEM001/SEM002 warnings); 105 generated*.g.csfiles updated to plural factory names; spot-checked Length / Mass / Temperature / Velocity1D / Frequency / Acceleration1D look right.dotnet test—Semantics.Testcannot restore in this sandbox (Microsoft.NETCore.App.Host.ubuntu.24.04-x64not in feeds); CI will run the rewritten tests.https://claude.ai/code/session_01Tj63Rddvs9frqLUgsjNEP5
Generated by Claude Code