Warn when loaded classes are replaced by another schema version

[ehennestad]

Motivation

Problem — A user who has created NWB objects and then reads a file of another schema version, or calls generateCore with another version, gets no sign that the objects they hold have changed. After creating a types.core.TimeSeries with 2.11.0 classes and calling generateCore("2.7.0"), the TimeSeries now uses the 2.7.0 class definition. When the new classes replace the old ones on the path, MATLAB redefines the loaded classes without a warning. The objects lose the values of properties the new version does not define, and nothing reports it.

Solution — MatNWB now warns when it replaces classes that are loaded in the session with another version, and lists each namespace with its previous and new version.

What changed

• generateCore, generateExtension, nwbInstallExtension and nwbRead issue the warning NWB:TypeCache:LoadedClassesReplaced when they replace a namespace with another version while classes of that namespace are loaded from the same folder.
• One warning covers all namespaces replaced in the same call, for example core and hdmf-common.
• Regenerating the same version, or switching versions before any class of the namespace has been used, does not warn.
• Reading a file of an older schema version after working with newer objects now warns. The existing test that reads a 2.1.0 file shows the warning in its output.

Implementation notes

• matnwb.internal.typecache.generateNamespaces compares the version in namespaces/<name>.mat of the save folder with the version it is about to put there. When they differ, it checks inmem for loaded classes of types.<namespace>, and which to confirm they were loaded from the save folder and not from another folder on the path.

Examples

Switching schema version with objects in memory

The snippet creates a TimeSeries with the 2.11.0 classes, then switches to 2.7.0.

generateCore("2.11.0");
timeSeries = types.core.TimeSeries(description="created with 2.11.0", data=1:10, data_unit="V", ...
    starting_time=0, starting_time_rate=10);
generateCore("2.7.0");
fprintf("types.core version: %s\n", types.core.Version())

Before — The switch is silent. timeSeries now uses the 2.7.0 class definition.

types.core version: 2.7.0

After — A warning lists the namespaces whose loaded classes were replaced, with the previous and new versions.

Warning: Classes that were loaded in this MATLAB session were replaced with
another version:
  hdmf-common 1.10.0 -> 1.8.0
  core 2.11.0 -> 2.7.0
Objects created before this point now use the classes of the new version, and
lose the values of properties that version does not define. Save or export the
objects you need before switching to another schema version.
types.core version: 2.7.0

How to test

Run the snippet above in a fresh MATLAB session. Then run the tests, which check the warning for a small test schema with loaded classes, and that there is no warning for the same version or for classes that are not loaded:

results = runtests("tests.unit.TypeCacheTest");
disp(table(results))

Checklist

• Have you ensured the PR description clearly describes the problem and solutions?
• Have you checked to ensure that there aren't other open or previously closed Pull Requests for the same change?
• If this PR fixes an issue, is the first line of the PR description fix #XX where XX is the issue number?

🤖 Generated with Claude Code