migrate-cache should also normalize enum cache files

[cmungall]

Problem

migrate-cache currently only handles */terms.csv files (curie, label, retrieved_at). It does not touch the enum membership cache files in cache/enums/*.csv (curie-only format).

These enum cache files suffer from the same ordering instability — they're written in non-deterministic order depending on which code path generated them (_save_enum_cache sorts, but _add_to_enum_cache appends). Existing files on disk may be unsorted even though newer code paths produce sorted output.

Expected

migrate-cache --sort-only should also find and sort enums/*.csv files by CURIE, so that a single command normalizes all cache artifacts.

Current workaround

for f in cache/enums/*.csv; do
  head -1 "$f" > /tmp/header.csv
  tail -n+2 "$f" | sort > /tmp/sorted.csv
  cat /tmp/header.csv /tmp/sorted.csv > "$f"
done

Context

• Discovered while testing v0.3.0rc1 in the dismech repo
• Related to term cache files should be free of spurious diffs #9 (cache stability)
• The enum caches have a simpler format (just curie column) so normalization is straightforward

[github-actions]

Summary

Type: Bug / Enhancement — gap in the migrate-cache CLI command

---

What the issue is about

The migrate-cache command (added to address #9) currently only normalizes cache/*/terms.csv files (3-column format: curie, label, retrieved_at). It does not handle the simpler cache/enums/*.csv files (single curie column), which suffer the same ordering instability.

Root cause

Two code paths write enum cache files with different ordering guarantees:

Method	Behavior
_save_enum_cache() (base.py:399)	Writes all values at once, sorted — produces a clean file
_add_to_enum_cache() (base.py:420)	Appends a single CURIE — results in insertion-order, non-deterministic output

The _add_to_enum_cache path is called during progressive validation (concepts, reachable_from, inherits lookups at lines 509, 517, 526). Files created via this path on disk may be unsorted even though new code produces sorted output. This means existing cache files in a repo can cause spurious diffs.

Current migrate-cache gap

Looking at cli.py:502, the command does:

terms_files = sorted(cache_dir.glob("*/terms.csv"))  # only hits terms.csv!

It completely skips cache/enums/*.csv.

Fix needed

Extend migrate-cache --sort-only (and by default) to also:

1. Find all cache/enums/*.csv files via cache_dir.glob("enums/*.csv")
2. Sort entries by curie (deduplicate if needed)
3. Rewrite if out of order

The format is simpler than terms.csv — just a single curie column, so the normalization logic is straightforward.

Related

• term cache files should be free of spurious diffs #9 (closed 2026-03-08): The original cache stability issue — fixed for terms.csv, this is the remaining gap for enum caches
• Discovered while testing v0.3.0rc1 in the dismech repo

Suggested workaround (from issue)

Until fixed, enum caches can be manually sorted:

for f in cache/enums/*.csv; do
  head -1 "$f" > /tmp/header.csv
  tail -n+2 "$f" | sort > /tmp/sorted.csv
  cat /tmp/header.csv /tmp/sorted.csv > "$f"
done

Implementation notes

• The fix is localized to migrate_cache() in cli.py — add a second glob for enums/*.csv
• Enum files only have one column (curie), so no timestamp deduplication logic is needed
• The --sort-only flag is already the right entry point; --refresh-labels should not apply to enum files (no labels to refresh)
• Should add a test in test_migrate_cache.py covering enum file normalization

@dragon-ai-agent please implement the fix for this issue: extend the migrate-cacheCLI command insrc/linkml_term_validator/cli.pyto also find and sortcache/enums/.csvfiles (singlecuriecolumn) in addition tocache//terms.csv. Add appropriate tests in tests/test_migrate_cache.py. The summary comment on issue #15 has full details.