Skip to content

Commit 47a5bb6

Browse files
committed
fix(presets): treat stale entries as unmet and unparseable versions as uncomparable
Addresses review feedback on #4250. A registry entry is not proof the extension can contribute. When the entry survives after .specify/extensions/<id> is removed, PresetResolver skips the extension outright -- both template lookup and layer collection guard on is_dir() -- so the preset is as inert as if it were never installed, while the surviving entry read as satisfied. Report that state as a distinct "stale" reason, ahead of the disabled and version checks, and remediate it with a forced reinstall rather than a plain add. The uncomparable-version guard also only covered non-string values. An unparseable string such as "unknown" passed it and reached version_satisfies(), which catches InvalidVersion and returns False -- reporting a mismatch against a version that was never actually evaluated, and contradicting the documented behaviour that unusable versions are not invented into mismatches. Check parseability before comparing so only real comparisons reach the warning. The test helper now creates the extension directory alongside the registry entry, matching what the installer does, with an opt-out for the stale case. Assisted-by: Claude Code (model: Claude Opus 5, autonomous)
1 parent db9a90d commit 47a5bb6

4 files changed

Lines changed: 130 additions & 18 deletions

File tree

‎presets/PUBLISHING.md‎

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -122,9 +122,10 @@ requires:
122122
Notes:
123123

124124
- The field is optional. A preset that declares nothing behaves exactly as before.
125-
- A dependency that is missing, disabled, or version-unsatisfied produces a **warning, not a failure** — the install still succeeds.
126-
- A disabled extension counts as unmet. Resolution skips disabled extensions, so the preset is just as inert as if it were absent.
127-
- The warning names an exact command for the missing and disabled cases. For a version mismatch it states the constraint to satisfy rather than naming a command, because `specify extension update` only moves forward to the catalog release and cannot satisfy an upper bound, a pin, or a downgrade.
125+
- A dependency that is missing, stale, disabled, or version-unsatisfied produces a **warning, not a failure** — the install still succeeds.
126+
- A disabled extension counts as unmet, and so does one whose registry entry survives after its files were removed. Resolution skips both, so the preset is just as inert as if the extension were absent.
127+
- The warning names an exact command for the missing, stale, and disabled cases. For a version mismatch it states the constraint to satisfy rather than naming a command, because `specify extension update` only moves forward to the catalog release and cannot satisfy an upper bound, a pin, or a downgrade.
128+
- A recorded version that cannot be parsed is treated as uncomparable rather than as a mismatch, so an extension whose registry version reads `unknown` is not reported as failing a constraint it was never evaluated against.
128129
- `required: false` documents an enhancing-but-optional extension and is never warned about.
129130
- Declare it in `preset.yml`, not only in your catalog entry. The catalog is not consulted for `--dev` and `--from <url>` installs, so the manifest is the only copy present on every install path.
130131

‎src/specify_cli/presets/__init__.py‎

Lines changed: 42 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -63,6 +63,20 @@ def _content_sha256(content: bytes) -> str:
6363
return hashlib.sha256(content).hexdigest()
6464

6565

66+
def _is_comparable_version(value: str) -> bool:
67+
"""Return whether a recorded version can be evaluated against a specifier.
68+
69+
``version_satisfies()`` answers "does not satisfy" for an unparseable
70+
version, which is indistinguishable from a genuine mismatch. Callers that
71+
need to tell those apart check here first.
72+
"""
73+
try:
74+
pkg_version.Version(value)
75+
except pkg_version.InvalidVersion:
76+
return False
77+
return True
78+
79+
6680
def _constitution_is_generated(
6781
project_root: Path,
6882
memory_constitution: Path,
@@ -971,9 +985,14 @@ def find_unmet_extension_dependencies(
971985
Returns:
972986
One entry per unsatisfied dependency, each with ``id``, the
973987
requested ``version`` specifier (``None`` when unconstrained), the
974-
``installed`` version (``None`` when absent), and a ``reason`` of
975-
``"missing"``, ``"disabled"``, or ``"version"``. Optional
976-
dependencies (``required: false``) are never reported.
988+
``installed`` version (``None`` when absent or unusable), and a
989+
``reason`` of ``"missing"``, ``"stale"``, ``"disabled"``, or
990+
``"version"``. Optional dependencies (``required: false``) are
991+
never reported.
992+
993+
A registry version that cannot be parsed is treated as
994+
uncomparable, not as a mismatch: the extension is installed and
995+
usable, and only its recorded version is unreadable.
977996
"""
978997
# Defense in depth, mirroring check_compatibility(): this method is
979998
# public and also reachable with a hand-built manifest object that
@@ -989,7 +1008,8 @@ def find_unmet_extension_dependencies(
9891008
if not declared:
9901009
return []
9911010

992-
registry = ExtensionRegistry(self.project_root / ".specify" / "extensions")
1011+
extensions_dir = self.project_root / ".specify" / "extensions"
1012+
registry = ExtensionRegistry(extensions_dir)
9931013
unmet: List[Dict[str, Any]] = []
9941014

9951015
for dep in declared:
@@ -1003,6 +1023,17 @@ def find_unmet_extension_dependencies(
10031023
installed_version if isinstance(installed_version, str) else None
10041024
)
10051025

1026+
# A registry entry is not proof the extension can contribute. If
1027+
# its directory is gone, PresetResolver skips it outright (both
1028+
# template lookup and layer collection guard on ``is_dir()``), so
1029+
# the preset is as inert as if it were never installed -- but the
1030+
# surviving entry would otherwise read as satisfied.
1031+
if not (extensions_dir / dep["id"]).is_dir():
1032+
unmet.append(
1033+
{**dep, "installed": installed_version, "reason": "stale"}
1034+
)
1035+
continue
1036+
10061037
# A disabled extension is registered but contributes nothing:
10071038
# resolution skips it (see _collect_extension_layers), so the
10081039
# preset is just as inert as if it were absent. Report it before
@@ -1018,10 +1049,13 @@ def find_unmet_extension_dependencies(
10181049
if not constraint:
10191050
continue
10201051

1021-
if installed_version is None:
1022-
# A registry entry without a usable version cannot be compared.
1023-
# Treat it as satisfied rather than inventing a failure, since
1024-
# the extension is demonstrably installed and enabled.
1052+
# A version that cannot be compared is not a mismatch. Absent or
1053+
# non-string is one way to be unusable; an unparseable string such
1054+
# as "unknown" is another, and version_satisfies() cannot tell them
1055+
# apart -- it catches InvalidVersion and returns False, which would
1056+
# report a mismatch against a version nobody can evaluate. Check
1057+
# parseability up front so only real comparisons reach the warning.
1058+
if installed_version is None or not _is_comparable_version(installed_version):
10251059
continue
10261060
if not version_satisfies(installed_version, constraint):
10271061
unmet.append(

‎src/specify_cli/presets/_commands.py‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -66,6 +66,12 @@ def _warn_unmet_extension_dependencies(manager, manifest) -> None:
6666
if reason == "missing":
6767
console.print(f" [yellow]{extension_id}[/yellow] is not installed")
6868
remedy = f"specify extension add {extension_id}"
69+
elif reason == "stale":
70+
console.print(
71+
f" [yellow]{extension_id}[/yellow] is registered but its "
72+
"files are missing"
73+
)
74+
remedy = f"specify extension add {extension_id} --force"
6975
elif reason == "disabled":
7076
console.print(f" [yellow]{extension_id}[/yellow] is installed but disabled")
7177
remedy = f"specify extension enable {extension_id}"

‎tests/test_presets.py‎

Lines changed: 78 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1163,10 +1163,19 @@ class TestPresetExtensionDependencies:
11631163
"""Test find_unmet_extension_dependencies (issue #4231)."""
11641164

11651165
@staticmethod
1166-
def _install_extension(project_dir, extension_id, version, enabled=True):
1167-
"""Register an installed extension the way the extension installer does."""
1166+
def _install_extension(
1167+
project_dir, extension_id, version, enabled=True, with_files=True
1168+
):
1169+
"""Register an installed extension the way the extension installer does.
1170+
1171+
``with_files=False`` leaves the registry entry without its directory,
1172+
reproducing the stale state left behind when the files are deleted out
1173+
from under the registry.
1174+
"""
11681175
extensions_dir = project_dir / ".specify" / "extensions"
11691176
extensions_dir.mkdir(parents=True, exist_ok=True)
1177+
if with_files:
1178+
(extensions_dir / extension_id).mkdir(parents=True, exist_ok=True)
11701179
registry_path = extensions_dir / ".registry"
11711180
data = {"schema_version": "1.0", "extensions": {}}
11721181
if registry_path.exists():
@@ -1282,15 +1291,21 @@ def test_optional_dependency_is_never_reported(
12821291
manifest
12831292
) == []
12841293

1285-
def test_registry_entry_without_version_is_not_a_failure(
1286-
self, project_dir, temp_dir, valid_pack_data
1294+
@pytest.mark.parametrize("bad_version", [None, 5, "unknown", "", "latest"])
1295+
def test_uncomparable_registry_version_is_not_a_mismatch(
1296+
self, project_dir, temp_dir, valid_pack_data, bad_version
12871297
):
1288-
"""An unusable registry version cannot be compared, so it is not invented
1289-
into a mismatch -- the extension is demonstrably installed."""
1298+
"""A version that cannot be evaluated must not be reported as a mismatch.
1299+
1300+
``version_satisfies()`` returns False for an unparseable version, which
1301+
is indistinguishable from a genuine mismatch -- so a string like
1302+
"unknown" would otherwise be reported as failing a constraint nobody
1303+
can actually evaluate it against.
1304+
"""
12901305
self._install_extension(project_dir, "speckit-inventory", "0.1.0")
12911306
registry_path = project_dir / ".specify" / "extensions" / ".registry"
12921307
data = json.loads(registry_path.read_text(encoding="utf-8"))
1293-
data["extensions"]["speckit-inventory"]["version"] = None
1308+
data["extensions"]["speckit-inventory"]["version"] = bad_version
12941309
registry_path.write_text(json.dumps(data), encoding="utf-8")
12951310

12961311
manifest = self._manifest(
@@ -1302,6 +1317,62 @@ def test_registry_entry_without_version_is_not_a_failure(
13021317
manifest
13031318
) == []
13041319

1320+
def test_stale_registry_entry_is_reported(
1321+
self, project_dir, temp_dir, valid_pack_data
1322+
):
1323+
"""A registry entry whose extension directory is gone counts as unmet.
1324+
1325+
PresetResolver guards on ``ext_dir.is_dir()`` in both template lookup
1326+
and layer collection, so a stale entry contributes nothing -- but the
1327+
surviving registry entry would otherwise read as satisfied.
1328+
"""
1329+
self._install_extension(
1330+
project_dir, "speckit-inventory", "0.1.0", with_files=False
1331+
)
1332+
manifest = self._manifest(temp_dir, valid_pack_data, ["speckit-inventory"])
1333+
1334+
unmet = PresetManager(project_dir).find_unmet_extension_dependencies(manifest)
1335+
1336+
assert len(unmet) == 1
1337+
assert unmet[0]["reason"] == "stale"
1338+
assert unmet[0]["installed"] == "0.1.0"
1339+
1340+
def test_stale_is_reported_ahead_of_disabled_and_version(
1341+
self, project_dir, temp_dir, valid_pack_data
1342+
):
1343+
"""Restoring the files is the prerequisite, so it is reported first."""
1344+
self._install_extension(
1345+
project_dir, "speckit-inventory", "0.1.0",
1346+
enabled=False, with_files=False,
1347+
)
1348+
manifest = self._manifest(
1349+
temp_dir, valid_pack_data,
1350+
[{"id": "speckit-inventory", "version": ">=9.0.0"}],
1351+
)
1352+
1353+
unmet = PresetManager(project_dir).find_unmet_extension_dependencies(manifest)
1354+
1355+
assert [dep["reason"] for dep in unmet] == ["stale"]
1356+
1357+
def test_stale_warning_suggests_a_forced_reinstall(self):
1358+
"""The stale remedy must restore the files, not re-add a registered id."""
1359+
manager = MagicMock()
1360+
manager.find_unmet_extension_dependencies.return_value = [
1361+
{
1362+
"id": "speckit-inventory",
1363+
"reason": "stale",
1364+
"installed": "0.1.0",
1365+
"version": None,
1366+
}
1367+
]
1368+
1369+
with console.capture() as capture:
1370+
_warn_unmet_extension_dependencies(manager, MagicMock())
1371+
1372+
output = strip_ansi(capture.get())
1373+
assert "its files are missing" in output
1374+
assert "specify extension add speckit-inventory --force" in output
1375+
13051376
def test_disabled_dependency_is_reported(
13061377
self, project_dir, temp_dir, valid_pack_data
13071378
):

0 commit comments

Comments
 (0)