feat(api) refactor api for ergonomics and type safety

[dselman]

Refactors the API.

The goals are:

1. To better align with the metamodel in terms of naming. We currently have things like RelationshipDeclaration and EnumValueDeclaration that are not declarations.
2. To improve type-safety, particularly around type introspection. The new ModelElement root class holds all the introspection methods, such as isConcept / isProperty etc. so we should be able to banish the error prone pattern of writing thing.isProperty?.() which is proliferating. This should also allow TypeScript code to refer to ModelElement in most cases, rather than ClassDeclaration | Property.
3. Reduce duplication and confusion between the different types of declaration we now have: concepts, enums, scalars, maps.
4. Reduce breaking changes as far as practicable.
5. Allow visitors to more easily and consistently switch over the meta-type so we can banish the use of instanceof in the visitors (and elsewhere)

Notes:

• Everything in a ModelFile is a ModelElement. This becomes our single place to put type introspection utilities.
• All Declarations (top-level named things in the Model File) extend Declaration
• Anything that can have a decorator applied is an instance of Decorated, except for ModelFile which exposes decorators but is itself not a Decorated (because we don't want a ModelFile to be a ModelElement).
• Things in a ModelFile that have properties are a ClassDeclaration. I.e. Maps and Scalars are Declarations, but they are not ClassDeclarations. An EnumDeclaration is a ClassDeclaration, because we consider EnumValues to be properties.
• RelationshipDeclaration is renamed to RelationshipProperty
• EnumValueDeclaration is renamed to EnumValue
• Decorator is now also a ModelElement
• Lots of changes for map serialisation to align with what we do for Fields (and removes lots of code). This includes storing DateTimes in map keys and values as dayjs instances for consistency with other DateTime fields. I think this will fix some bugs. E.g. Map does not support polymorphic values #769 and ensures type conversion to/from JSON is consistent.

Changes

• Adds a ModelElement root class to hold all meta-type introspection methods
• Refactor Decorated to extend ModelElement
• RelationshipDeclaration class renamed to RelationshipProperty
• EnumValueDeclaration class renamed to EnumValue

Flags

Screenshots or Video

Related Issues

• Issue #
• Pull Request #

Author Checklist

• Ensure you provide a DCO sign-off for your commits using the --signoff option of git commit.
• Vital features and changes captured in unit and/or integration tests
• Commits messages follow AP format
• Extend the documentation, if necessary
• Merging to main from fork:branchname

[mttrbrts]

How closely does this mirror the metamodel definition now?

[dselman]

Tests pass. Now need to look at the code coverage.

[mttrbrts]

😌