Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.
Python aicode-complexitycode-healthcode-intelligencecode-qualitydead-codedeveloper-toolsdocumentationgit-analyticsmcpopen-sourcepythonrefactoringstatic-analysistechnical-debt
feat(upgrade): store-format versioning + reindex-free upgrade core (#553)
Raghav Chamadiyaf366cdc175f4
diff --git a/packages/cli/src/repowise/cli/commands/update_cmd/command.py b/packages/cli/src/repowise/cli/commands/update_cmd/command.pyindex 2a5bea4cf..c5e01bbd7 100644--- a/packages/cli/src/repowise/cli/commands/update_cmd/command.py+++ b/packages/cli/src/repowise/cli/commands/update_cmd/command.py@@ -12,6 +12,7 @@ from __future__ import annotationsimport timeimport click+import structlogfrom repowise.cli.helpers import (acquire_update_lock,@@ -57,6 +58,8 @@ from .reporting import ()from .workspace import _workspace_update+log = structlog.get_logger(__name__)+@click.command("update")@click.argument("path", required=False, default=None)@@ -343,6 +346,29 @@ def update_command(atexit.register(release_update_lock, repo_path)atexit.register(clear_update_queued, repo_path)+ # --- Store-format upgrade assessment --------------------------------+ # Single decision point for "does upgrading repowise need to touch this+ # store". Runs any no-LLM auto actions (e.g. re-embed after an embedding+ # model change); reindex is only ever recommended, never forced here.+ # Placed after the single-flight lock so an auto re-embed (a full vector+ # rebuild) can't race a concurrent update. Best-effort: the upgrade layer+ # must never block a routine update.+ try:+ from repowise.cli.upgrade import apply_upgrade, assess_store++ verdict = assess_store(repo_path)+ if not verdict.is_noop:+ if verdict.reindex_recommended and verdict.reindex_command:+ console.print(f"[yellow]Reindex recommended:[/yellow] {verdict.reindex_command}")+ if verdict.user_notice:+ console.print(f"[dim]{verdict.user_notice}[/dim]")+ if verdict.actions and not dry_run:+ for action in verdict.actions:+ console.print(f"[dim]Upgrade: {action.reason}[/dim]")+ run_async(apply_upgrade(repo_path, verdict))+ except Exception as exc: # never block a routine update on the upgrade layer+ log.debug("store_upgrade_skipped", error=str(exc))+render_header(repo_path, base_ref, head)from repowise.core.ingestion import ChangeDetectordiff --git a/packages/cli/src/repowise/cli/helpers.py b/packages/cli/src/repowise/cli/helpers.pyindex 10d18953a..e0762151f 100644--- a/packages/cli/src/repowise/cli/helpers.py+++ b/packages/cli/src/repowise/cli/helpers.py@@ -183,8 +183,20 @@ def load_state(repo_path: Path) -> dict[str, Any]:def save_state(repo_path: Path, state: dict[str, Any]) -> None:- """Write *state* to ``.repowise/state.json``."""+ """Write *state* to ``.repowise/state.json``.++ Every persist stamps the store-format markers (``store_format_version`` and+ the ``written_by_version`` package version that wrote it) so the upgrade+ layer always has a current record of the store's shape and provenance.+ """ensure_repowise_dir(repo_path)+ try:+ from repowise.cli import __version__ as _pkg_version+ from repowise.core.upgrade import stamp as _stamp_store_version++ _stamp_store_version(state, package_version=_pkg_version)+ except Exception: # never let stamping block a persist+ passstate_path = get_repowise_dir(repo_path) / STATE_FILENAMEstate_path.write_text(json.dumps(state, indent=2), encoding="utf-8")@@ -347,9 +359,7 @@ def write_update_queued(repo_path: Path, head: str | None) -> None:returnpayload = {"target_commit": head, "queued_at": time.time()}try:- _update_queued_path(repo_path).write_text(- json.dumps(payload), encoding="utf-8"- )+ _update_queued_path(repo_path).write_text(json.dumps(payload), encoding="utf-8")except OSError:pass@@ -841,6 +851,7 @@ def validate_provider_config(provider_name: str | None = None) -> list[str]:if provider_name == "opencode":import shutil+if not shutil.which("opencode"):warnings.append("Provider 'opencode' requires the opencode CLI.\n"@@ -1061,7 +1072,9 @@ def resolve_command_target(raise click.UsageError("--workspace and --no-workspace are mutually exclusive.")if repo_alias is not None and no_workspace_flag:- raise click.UsageError("--repo <alias> implies workspace mode, but --no-workspace was passed.")+ raise click.UsageError(+ "--repo <alias> implies workspace mode, but --no-workspace was passed."+ )explicit_path = path is not Nonebase_path = resolve_repo_path(path)@@ -1100,14 +1113,12 @@ def resolve_command_target(ws_config = _load_ws(ws_root)if ws_config is None:raise WorkspaceNotFound(- f"Found workspace config at {ws_root} but couldn't load it. "- "Is it valid YAML?"+ f"Found workspace config at {ws_root} but couldn't load it. Is it valid YAML?")if repo_alias is not None and ws_config.get_repo(repo_alias) is None:available = ", ".join(ws_config.repo_aliases()) or "(none)"raise click.UsageError(- f"Unknown repo alias '{repo_alias}' in workspace. "- f"Available: {available}"+ f"Unknown repo alias '{repo_alias}' in workspace. Available: {available}")reason = "via --workspace flag" if workspace_flag else f"via --repo {repo_alias}"return CommandTarget(diff --git a/packages/cli/src/repowise/cli/upgrade.py b/packages/cli/src/repowise/cli/upgrade.pynew file mode 100644index 000000000..16e08ae28--- /dev/null+++ b/packages/cli/src/repowise/cli/upgrade.py@@ -0,0 +1,89 @@+"""CLI-side execution of the core upgrade decision layer.++:mod:`repowise.core.upgrade` decides *what* an upgrade needs; this module is the+edge that *executes* the no-LLM auto actions (it knows how to build embedders+and where the parse cache lives) and assembles the inputs ``assess`` needs from+the on-disk store. CLI commands call :func:`assess_store` to get a verdict and+:func:`apply_upgrade` to run any automatic, never-destructive steps.++Reindex is only ever recommended via the verdict, never run here.++Not to be confused with :mod:`repowise.cli.commands.upgrade_flow`, which is the+*index-tier* upgrade (``update --full``: fast -> full). This module is the+*store-format* upgrade across repowise versions.+"""++from __future__ import annotations++from pathlib import Path++import structlog++from repowise.core.upgrade import (+ UpgradeContext,+ UpgradeVerdict,+ apply_auto,+ assess,+)++from .helpers import REPOWISE_DIR, load_config, load_state++log = structlog.get_logger(__name__)+++class _CliUpgradeContext:+ """Concrete :class:`UpgradeContext` backed by the CLI provider stack."""++ def __init__(self, repo_path: Path) -> None:+ self._repo_path = repo_path++ async def reembed_vectors(self) -> None:+ # Reuse the exact reindex path: rebuild vectors from existing wiki+ # pages with the resolved embedder. No LLM calls, only embedding calls.+ from .commands.reindex_cmd import _reindex++ await _reindex(self._repo_path, "auto", 20)++ def drop_parse_cache(self) -> None:+ cache = self._repo_path / REPOWISE_DIR / "parse_cache.pkl"+ if cache.exists():+ cache.unlink()+++def _current_embedding_model() -> str | None:+ """The embedding model the running build would resolve right now."""+ try:+ from .providers.embedders import resolve_embedder, resolve_embedding_model++ return resolve_embedding_model(resolve_embedder(None))+ except Exception:+ return None+++def assess_store(repo_path: Path) -> UpgradeVerdict:+ """Assess what upgrading this store to the running build requires.++ Pure read: loads ``state.json`` + ``config.yaml`` and the currently+ resolved embedding model, then defers the decision to the core layer.+ """+ state = load_state(repo_path)+ config = load_config(repo_path)+ recorded_model = config.get("embedding_model")+ return assess(+ state,+ recorded_embedding_model=recorded_model if isinstance(recorded_model, str) else None,+ current_embedding_model=_current_embedding_model(),+ )+++async def apply_upgrade(repo_path: Path, verdict: UpgradeVerdict) -> None:+ """Run the verdict's automatic (no-LLM) actions. Best-effort, never raises."""+ if not verdict.actions:+ return+ ctx: UpgradeContext = _CliUpgradeContext(repo_path)+ ran = await apply_auto(verdict, ctx)+ if ran:+ log.info("upgrade_applied", actions=[str(k) for k in ran])+++__all__ = ["apply_upgrade", "assess_store"]diff --git a/packages/core/src/repowise/core/ingestion/parse_cache.py b/packages/core/src/repowise/core/ingestion/parse_cache.pyindex aec7d78f6..7d08566db 100644--- a/packages/core/src/repowise/core/ingestion/parse_cache.py+++ b/packages/core/src/repowise/core/ingestion/parse_cache.py@@ -5,8 +5,9 @@ re-parses the whole repo when one file changed, and large-repo inits payminutes of tree-sitter time. A ParsedFile is a pure function of the file*bytes* and the parser itself, so it caches safely keyed by``(relative path, content hash)`` under a parser fingerprint (the compiled-``.scm`` query sources + the package version) that invalidates the whole-cache when extraction rules change.+``.scm`` query sources + ``PARSER_SCHEMA_VERSION``) that invalidates the whole+cache when extraction rules change. The fingerprint excludes the package+version on purpose so unrelated releases keep the cache warm.Entries are stored as pickle *bytes* snapshotted at parse time — downstreamgraph builds mutate ParsedFile in place (``Import.resolved_file``,@@ -48,18 +49,21 @@ __all__ = ["ParseCache", "parser_fingerprint"]def parser_fingerprint() -> str:"""Fingerprint of everything that determines a ParsedFile besides bytes.- Hashes every ``.scm`` query source (extraction rules) plus the package- version (parser/extractor code changes ship as releases). A mismatch- invalidates the whole cache — correctness over reuse.+ Hashes every ``.scm`` query source (extraction rules) plus+ ``PARSER_SCHEMA_VERSION`` (Python-side extraction logic). Deliberately+ *not* the package ``__version__``: an unrelated release must not churn a+ user's whole parse cache. The schema version is bumped only when parser /+ extractor behaviour actually changes, so a mismatch still invalidates the+ cache when correctness demands it. See :mod:`repowise.core.upgrade.version`."""h = hashlib.sha256()h.update(f"cache-version:{_CACHE_VERSION}".encode())try:- from repowise.core import __version__+ from repowise.core.upgrade.version import PARSER_SCHEMA_VERSION- h.update(f"version:{__version__}".encode())+ h.update(f"parser-schema:{PARSER_SCHEMA_VERSION}".encode())except Exception:- h.update(b"version:unknown")+ h.update(b"parser-schema:unknown")queries_dir = Path(__file__).parent / "queries"try:for scm in sorted(queries_dir.glob("*.scm")):diff --git a/packages/core/src/repowise/core/upgrade/__init__.py b/packages/core/src/repowise/core/upgrade/__init__.pynew file mode 100644index 000000000..6e7eb6f0d--- /dev/null+++ b/packages/core/src/repowise/core/upgrade/__init__.py@@ -0,0 +1,45 @@+"""Store-format versioning and the upgrade decision layer.++This package is the single source of truth for "what shape is the ``.repowise``+store, and does upgrading repowise need to touch it." :func:`assess` returns a+pure :class:`UpgradeVerdict`; the CLI and server present it and (for no-LLM auto+actions) execute it via :func:`apply_auto`. Reindex is only ever *recommended*,+never forced.+"""++from __future__ import annotations++from .manager import UpgradeContext, apply_auto, assess, stamp+from .registry import MIGRATIONS, Migration, migrations_between+from .verdict import (+ UpgradeAction,+ UpgradeActionKind,+ UpgradeTier,+ UpgradeVerdict,+)+from .version import (+ EMBEDDING_MODEL_KEY,+ PARSER_SCHEMA_VERSION,+ STORE_FORMAT_VERSION,+ STORE_FORMAT_VERSION_KEY,+ WRITTEN_BY_VERSION_KEY,+)++__all__ = [+ "EMBEDDING_MODEL_KEY",+ "MIGRATIONS",+ "PARSER_SCHEMA_VERSION",+ "STORE_FORMAT_VERSION",+ "STORE_FORMAT_VERSION_KEY",+ "WRITTEN_BY_VERSION_KEY",+ "Migration",+ "UpgradeAction",+ "UpgradeActionKind",+ "UpgradeContext",+ "UpgradeTier",+ "UpgradeVerdict",+ "apply_auto",+ "assess",+ "migrations_between",+ "stamp",+]diff --git a/packages/core/src/repowise/core/upgrade/manager.py b/packages/core/src/repowise/core/upgrade/manager.pynew file mode 100644index 000000000..c7624642e--- /dev/null+++ b/packages/core/src/repowise/core/upgrade/manager.py@@ -0,0 +1,175 @@+"""The single decision point for store upgrades.++:func:`assess` is pure: given the persisted ``state`` mapping and the running+build's versions, it returns an :class:`UpgradeVerdict`. It performs no I/O and+no side effects, so it is trivially unit-testable and identical whether called+from the CLI or the server.++:func:`apply_auto` runs the no-LLM auto actions a verdict carries, dispatching+through an injected :class:`UpgradeContext`. The context lives at the edge (the+CLI knows how to build embedders and find the parse cache); core stays free of+those dependencies.+"""++from __future__ import annotations++from collections.abc import Mapping+from typing import Protocol, runtime_checkable++import structlog++from .registry import migrations_between+from .verdict import (+ UpgradeAction,+ UpgradeActionKind,+ UpgradeTier,+ UpgradeVerdict,+)+from .version import (+ STORE_FORMAT_VERSION,+ STORE_FORMAT_VERSION_KEY,+ WRITTEN_BY_VERSION_KEY,+)++log = structlog.get_logger(__name__)+++@runtime_checkable+class UpgradeContext(Protocol):+ """Edge-supplied executor for a verdict's auto actions.++ Each method is best-effort: an executor that cannot perform an action (or+ fails) should log and return without raising, so a routine ``update`` never+ breaks on an opportunistic upgrade step.+ """++ async def reembed_vectors(self) -> None:+ """Rebuild vector embeddings from existing wiki pages (no LLM)."""+ ...++ def drop_parse_cache(self) -> None:+ """Remove the parse cache so the next ingest re-parses from source."""+ ...+++def assess(+ state: Mapping[str, object],+ *,+ current_store_version: int = STORE_FORMAT_VERSION,+ recorded_embedding_model: str | None = None,+ current_embedding_model: str | None = None,+) -> UpgradeVerdict:+ """Decide what (if anything) upgrading this store requires.++ ``state`` is the parsed ``state.json``. Missing version fields mean a legacy+ store: ``store_format_version`` defaults to 0. The verdict's tier is the max+ severity across the migrations spanned, escalated by an embedding-model+ mismatch (which adds a no-LLM re-embed action).++ ``recorded_embedding_model`` is the model the existing vectors were built+ with (the pinned ``embedding_model`` in ``config.yaml``, its canonical home;+ callers pass it explicitly). ``current_embedding_model`` is what the running+ build resolves now; a difference triggers a re-embed.+ """+ from_version = _coerce_int(state.get(STORE_FORMAT_VERSION_KEY), default=0)+ written_by = _coerce_str(state.get(WRITTEN_BY_VERSION_KEY))++ spanned = migrations_between(from_version, current_store_version)+ tier = UpgradeTier.COMPATIBLE+ actions: list[UpgradeAction] = []+ summaries: list[str] = []+ reindex_command: str | None = None+ notice_parts: list[str] = []++ for migration in spanned:+ tier = max(tier, migration.tier)+ summaries.append(migration.summary)+ if migration.tier == UpgradeTier.REINDEX_RECOMMENDED:+ reindex_command = "repowise init --force"+ notice_parts.append(migration.summary)+ elif migration.action is not None:+ actions.append(UpgradeAction(kind=migration.action, reason=migration.summary))++ # Embedding-model mismatch is orthogonal to the format version: a store can+ # be format-current yet hold vectors from a different embedding model (#426),+ # which silently degrades search. Re-embedding has no LLM cost, so it is an+ # AUTO action rather than a reindex recommendation.+ recorded_model = recorded_embedding_model+ if recorded_model and current_embedding_model and recorded_model != current_embedding_model:+ tier = max(tier, UpgradeTier.AUTO)+ actions.append(+ UpgradeAction(+ kind=UpgradeActionKind.REEMBED_VECTORS,+ reason=(+ f"embedding model changed ({recorded_model} -> "+ f"{current_embedding_model}); re-embedding for search parity"+ ),+ )+ )++ user_notice = " ".join(notice_parts) if notice_parts else None++ return UpgradeVerdict(+ tier=tier,+ from_store_version=from_version,+ to_store_version=current_store_version,+ written_by=written_by,+ actions=tuple(actions),+ user_notice=user_notice,+ reindex_command=reindex_command,+ summaries=tuple(summaries),+ )+++async def apply_auto(verdict: UpgradeVerdict, ctx: UpgradeContext) -> list[UpgradeActionKind]:+ """Run the verdict's auto actions through *ctx*. Best-effort.++ Returns the kinds that ran successfully. Never raises: a failed auto action+ is logged and skipped so a routine update is never blocked by it. A+ ``REINDEX_RECOMMENDED`` verdict carries no actions, so nothing runs — the+ recommendation is surfaced by the presenter layer, never forced here.+ """+ ran: list[UpgradeActionKind] = []+ for action in verdict.actions:+ try:+ if action.kind == UpgradeActionKind.REEMBED_VECTORS:+ await ctx.reembed_vectors()+ elif action.kind == UpgradeActionKind.DROP_PARSE_CACHE:+ ctx.drop_parse_cache()+ else: # pragma: no cover - defensive; new kinds add a branch+ log.debug("upgrade_action_unhandled", kind=str(action.kind))+ continue+ ran.append(action.kind)+ log.info("upgrade_auto_action", kind=str(action.kind), reason=action.reason)+ except Exception as exc:+ log.warning("upgrade_auto_action_failed", kind=str(action.kind), error=str(exc))+ return ran+++def stamp(state: dict[str, object], *, package_version: str | None) -> dict[str, object]:+ """Write the current store-format markers into *state* in place and return it.++ Called on every persist so the store always records the format and the build+ that wrote it. ``embedding_model`` is stamped separately by the persistence+ layer that knows the resolved embedder.+ """+ state[STORE_FORMAT_VERSION_KEY] = STORE_FORMAT_VERSION+ if package_version:+ state[WRITTEN_BY_VERSION_KEY] = package_version+ return state+++def _coerce_int(value: object, *, default: int) -> int:+ try:+ return int(value) # type: ignore[arg-type]+ except (TypeError, ValueError):+ return default+++def _coerce_str(value: object) -> str | None:+ if isinstance(value, str) and value:+ return value+ return None+++__all__ = ["UpgradeContext", "apply_auto", "assess", "stamp"]diff --git a/packages/core/src/repowise/core/upgrade/registry.py b/packages/core/src/repowise/core/upgrade/registry.pynew file mode 100644index 000000000..79642f10a--- /dev/null+++ b/packages/core/src/repowise/core/upgrade/registry.py@@ -0,0 +1,68 @@+"""The append-only registry of store-format migrations.++Each :class:`Migration` describes the upgrade impact of moving the store *to*+a given :data:`~repowise.core.upgrade.version.STORE_FORMAT_VERSION`. Adding a+future migration is a single appended entry — there is no control flow to edit,+which keeps the upgrade path scalable as the format evolves.++A migration applies to a store whose recorded version is ``< to_version`` and+whose target (the running build) is ``>= to_version``; :func:`migrations_between`+returns exactly those, in order.+"""++from __future__ import annotations++from collections.abc import Sequence+from dataclasses import dataclass++from .verdict import UpgradeActionKind, UpgradeTier+++@dataclass(frozen=True, slots=True)+class Migration:+ """One step in the store-format history.++ ``to_version``+ The store format version this entry introduces.+ ``tier``+ The upgrade impact (see :class:`UpgradeTier`).+ ``summary``+ One line shown to the user in "what's new" / upgrade notices.+ ``action``+ Optional auto action to run for ``AUTO``/``RE_PARSE`` tiers. ``None``+ for ``COMPATIBLE`` (nothing to do) and ``REINDEX_RECOMMENDED`` (never+ auto-run — we only inform).+ """++ to_version: int+ tier: UpgradeTier+ summary: str+ action: UpgradeActionKind | None = None+++#: Ordered history of store-format migrations. APPEND ONLY — never reorder or+#: mutate shipped entries; older stores in the wild are assessed against this.+MIGRATIONS: tuple[Migration, ...] = (+ # v0 -> v1: the baseline. Legacy stores (no ``store_format_version`` field)+ # are version 0; reaching v1 needs nothing beyond the additive schema+ # reconcile that ``init_db`` already performs on every open.+ Migration(+ to_version=1,+ tier=UpgradeTier.COMPATIBLE,+ summary="Baseline store format (additive schema reconcile is automatic).",+ action=None,+ ),+)+++def migrations_between(from_version: int, to_version: int) -> Sequence[Migration]:+ """Return migrations with ``from_version < to_version <= to_version``.++ Ordered ascending by ``to_version``. Empty when the store is already at or+ ahead of the target (e.g. a store written by a newer repowise opened by an+ older one — we never downgrade, just report nothing to do).+ """+ return tuple(m for m in MIGRATIONS if from_version < m.to_version <= to_version)+++__all__ = ["MIGRATIONS", "Migration", "migrations_between"]diff --git a/packages/core/src/repowise/core/upgrade/verdict.py b/packages/core/src/repowise/core/upgrade/verdict.pynew file mode 100644index 000000000..1baad4c7f--- /dev/null+++ b/packages/core/src/repowise/core/upgrade/verdict.py@@ -0,0 +1,88 @@+"""Value types describing the outcome of an upgrade assessment.++These are pure data: :class:`UpgradeManager` produces an :class:`UpgradeVerdict`+and never performs side effects itself. The CLI and server consume the verdict+as their single source of truth, so neither duplicates upgrade decision logic.+"""++from __future__ import annotations++import enum+from dataclasses import dataclass, field+++class UpgradeTier(enum.IntEnum):+ """Severity of what an upgrade requires, ordered low to high.++ Ordering matters: when several migrations apply across a version span, the+ overall tier is the maximum (most severe) of them.+ """++ #: Nothing to do. Additive schema reconcile (already automatic) covers it.+ COMPATIBLE = 0+ #: A no-LLM action runs automatically in-band (e.g. re-embed vectors).+ AUTO = 1+ #: The parse cache is rebuilt — cheap, automatic, happens on next ingest.+ RE_PARSE = 2+ #: Genuinely breaking. Never auto-run; surface a notice + exact command.+ REINDEX_RECOMMENDED = 3+++class UpgradeActionKind(enum.StrEnum):+ """Auto-runnable actions, dispatched through an injected context.++ Keeping these as opaque kinds (rather than callables) keeps the core+ decision layer free of any dependency on the CLI provider stack — the+ executor that knows how to build embedders lives at the edge.+ """++ #: Re-embed all wiki pages + decisions via the existing reindex path.+ REEMBED_VECTORS = "reembed_vectors"+ #: Drop the parse cache so the next ingest re-parses from source.+ DROP_PARSE_CACHE = "drop_parse_cache"+++@dataclass(frozen=True, slots=True)+class UpgradeAction:+ """One auto action to run, with a human-readable reason."""++ kind: UpgradeActionKind+ reason: str+++@dataclass(frozen=True, slots=True)+class UpgradeVerdict:+ """The full assessment of upgrading a store to the running version.++ ``tier`` is the headline. ``actions`` are the no-LLM steps an executor+ should run for ``AUTO``/``RE_PARSE`` tiers. ``user_notice`` and+ ``reindex_command`` are populated for anything the user should see (most+ importantly the ``REINDEX_RECOMMENDED`` case, which we only ever inform).+ """++ tier: UpgradeTier+ from_store_version: int+ to_store_version: int+ written_by: str | None = None+ actions: tuple[UpgradeAction, ...] = field(default_factory=tuple)+ user_notice: str | None = None+ reindex_command: str | None = None+ #: Concise per-version highlights, filled by the presenter layer (Phase 2).+ summaries: tuple[str, ...] = field(default_factory=tuple)++ @property+ def is_noop(self) -> bool:+ """True when the upgrade needs nothing and warrants no message."""+ return self.tier == UpgradeTier.COMPATIBLE and not self.actions and not self.user_notice++ @property+ def reindex_recommended(self) -> bool:+ return self.tier == UpgradeTier.REINDEX_RECOMMENDED+++__all__ = [+ "UpgradeAction",+ "UpgradeActionKind",+ "UpgradeTier",+ "UpgradeVerdict",+]diff --git a/packages/core/src/repowise/core/upgrade/version.py b/packages/core/src/repowise/core/upgrade/version.pynew file mode 100644index 000000000..a7e8c6d62--- /dev/null+++ b/packages/core/src/repowise/core/upgrade/version.py@@ -0,0 +1,55 @@+"""Authoritative version constants for the on-disk store format.++These two integers are the *single source of truth* for "what shape is the+``.repowise`` store, and does upgrading repowise need to touch it." They are+deliberately decoupled from the package ``__version__`` so that ordinary+releases (which ship code changes but no store-format change) never invalidate+a user's cached work.++When to bump+------------+``STORE_FORMAT_VERSION``+ Bump by one whenever the *meaning or layout* of the persisted store changes+ in a way the running code must react to (a new required column the additive+ reconcile cannot back-fill, a vector-store layout change, a re-derivation+ that older stores lack). Every bump MUST add a matching entry to+ :data:`repowise.core.upgrade.registry.MIGRATIONS` declaring its upgrade+ impact tier. The overwhelming default for a release is to leave this alone.++``PARSER_SCHEMA_VERSION``+ Bump by one only when parser / extractor logic changes such that a cached+ ``ParsedFile`` from an older build is no longer correct (tree-sitter query+ edits are already covered by hashing the ``.scm`` sources; bump this for+ Python-side extraction changes). Bumping it invalidates the parse cache and+ forces a cheap, automatic re-parse on the next ingest. Leaving package+ ``__version__`` out of the fingerprint is the whole point: unrelated+ releases keep the cache warm.+"""++from __future__ import annotations++#: Current on-disk store format. Stamped into ``state.json`` as+#: ``store_format_version`` on every persist. Legacy stores predating this+#: field are treated as version 0.+STORE_FORMAT_VERSION: int = 1++#: Current parser/extractor schema. Folded into the parse-cache fingerprint in+#: place of the package version. See :mod:`repowise.core.ingestion.parse_cache`.+PARSER_SCHEMA_VERSION: int = 1++#: state.json key holding the store format version that wrote the store.+STORE_FORMAT_VERSION_KEY = "store_format_version"++#: state.json key holding the package ``__version__`` that last wrote the store.+WRITTEN_BY_VERSION_KEY = "written_by_version"++#: state.json key holding the embedding model id the vectors were built with.+EMBEDDING_MODEL_KEY = "embedding_model"++__all__ = [+ "EMBEDDING_MODEL_KEY",+ "PARSER_SCHEMA_VERSION",+ "STORE_FORMAT_VERSION",+ "STORE_FORMAT_VERSION_KEY",+ "WRITTEN_BY_VERSION_KEY",+]diff --git a/tests/unit/upgrade/__init__.py b/tests/unit/upgrade/__init__.pynew file mode 100644index 000000000..e69de29bbdiff --git a/tests/unit/upgrade/test_cli_executor.py b/tests/unit/upgrade/test_cli_executor.pynew file mode 100644index 000000000..b5a782ec4--- /dev/null+++ b/tests/unit/upgrade/test_cli_executor.py@@ -0,0 +1,69 @@+"""Tests for the CLI-side upgrade executor (``repowise.cli.upgrade``).++These cover the edge that ``assess`` itself does not: reading the store's+``config.yaml`` for the pinned embedding model, the ``UpgradeContext``+implementation's side effects, and the best-effort resolution of the current+embedding model.+"""++from __future__ import annotations++from pathlib import Path++import pytest++from repowise.cli import upgrade as cliup+from repowise.cli.helpers import save_config, save_state+from repowise.core.upgrade import UpgradeActionKind, UpgradeTier+++def test_assess_store_clean_on_fresh_store(tmp_path: Path):+ save_state(tmp_path, {"last_sync_commit": "abc"})+ verdict = cliup.assess_store(tmp_path)+ # save_state stamps the current format, so a freshly written store is a noop.+ assert verdict.is_noop+ assert verdict.tier == UpgradeTier.COMPATIBLE+++def test_assess_store_detects_embedding_drift(tmp_path: Path, monkeypatch):+ save_state(tmp_path, {"last_sync_commit": "abc"})+ save_config(+ tmp_path,+ "openai",+ "gpt-5.4-nano",+ "openai",+ embedding_model="text-embedding-3-large",+ )+ # Running build now resolves a different model.+ monkeypatch.setattr(cliup, "_current_embedding_model", lambda: "text-embedding-3-small")+ verdict = cliup.assess_store(tmp_path)+ assert verdict.tier == UpgradeTier.AUTO+ assert any(a.kind == UpgradeActionKind.REEMBED_VECTORS for a in verdict.actions)+++def test_drop_parse_cache_unlinks_file(tmp_path: Path):+ cache = tmp_path / ".repowise" / "parse_cache.pkl"+ cache.parent.mkdir(parents=True)+ cache.write_bytes(b"stale")+ ctx = cliup._CliUpgradeContext(tmp_path)+ ctx.drop_parse_cache()+ assert not cache.exists()+++def test_drop_parse_cache_is_noop_when_absent(tmp_path: Path):+ ctx = cliup._CliUpgradeContext(tmp_path)+ ctx.drop_parse_cache() # must not raise when the cache file is missing+++def test_current_embedding_model_swallows_errors(monkeypatch):+ def _boom(*_a, **_k):+ raise RuntimeError("no providers")++ monkeypatch.setattr("repowise.cli.providers.embedders.resolve_embedder", _boom, raising=False)+ assert cliup._current_embedding_model() is None+++async def test_apply_upgrade_noop_when_no_actions(tmp_path: Path):+ verdict = cliup.assess_store(tmp_path) # empty store -> noop verdict+ await cliup.apply_upgrade(tmp_path, verdict) # must not raise / do nothingdiff --git a/tests/unit/upgrade/test_manager.py b/tests/unit/upgrade/test_manager.pynew file mode 100644index 000000000..fea4b51c7--- /dev/null+++ b/tests/unit/upgrade/test_manager.py@@ -0,0 +1,198 @@+"""Unit tests for the store-format upgrade decision layer.++``assess`` is pure, so these exercise the full decision matrix directly:+legacy stores, current stores, embedding-model drift, and the+recommend-never-force contract for a synthetic breaking migration. ``apply_auto``+is verified to dispatch through an injected context and to never raise.+"""++from __future__ import annotations++import pytest++from repowise.core.upgrade import (+ STORE_FORMAT_VERSION,+ UpgradeAction,+ UpgradeActionKind,+ UpgradeTier,+ UpgradeVerdict,+ apply_auto,+ assess,+ stamp,+)+from repowise.core.upgrade import registry as registry_mod+from repowise.core.upgrade.registry import Migration, migrations_between++# --- assess: version-span tiers ------------------------------------------+++def test_legacy_store_is_compatible_noop():+ """A store with no version fields (version 0) reaching v1 needs nothing."""+ verdict = assess({})+ assert verdict.from_store_version == 0+ assert verdict.to_store_version == STORE_FORMAT_VERSION+ assert verdict.tier == UpgradeTier.COMPATIBLE+ assert verdict.is_noop+ assert not verdict.actions+++def test_current_store_is_noop():+ verdict = assess({"store_format_version": STORE_FORMAT_VERSION, "written_by_version": "0.21.0"})+ assert verdict.is_noop+ assert verdict.written_by == "0.21.0"+++def test_store_from_future_version_is_noop():+ """A store written by a newer build (we never downgrade) reports nothing."""+ verdict = assess({"store_format_version": STORE_FORMAT_VERSION + 5})+ assert verdict.is_noop+ assert verdict.tier == UpgradeTier.COMPATIBLE+++# --- assess: embedding-model drift ---------------------------------------+++def test_embedding_model_change_triggers_auto_reembed():+ verdict = assess(+ {"store_format_version": STORE_FORMAT_VERSION},+ recorded_embedding_model="text-embedding-3-large",+ current_embedding_model="text-embedding-3-small",+ )+ assert verdict.tier == UpgradeTier.AUTO+ assert not verdict.is_noop+ kinds = [a.kind for a in verdict.actions]+ assert UpgradeActionKind.REEMBED_VECTORS in kinds+++def test_same_embedding_model_is_noop():+ verdict = assess(+ {"store_format_version": STORE_FORMAT_VERSION},+ recorded_embedding_model="text-embedding-3-large",+ current_embedding_model="text-embedding-3-large",+ )+ assert verdict.is_noop+++def test_missing_current_embedding_model_does_not_falsely_trigger():+ """When the running build resolves no model (env unset), do not re-embed."""+ verdict = assess(+ {"store_format_version": STORE_FORMAT_VERSION},+ recorded_embedding_model="text-embedding-3-large",+ current_embedding_model=None,+ )+ assert verdict.is_noop+++def test_no_recorded_model_means_no_embedding_check():+ """With no pinned model to compare against, never re-embed."""+ verdict = assess(+ {"store_format_version": STORE_FORMAT_VERSION},+ recorded_embedding_model=None,+ current_embedding_model="model-b",+ )+ assert verdict.is_noop+++# --- assess: recommend-never-force for breaking migrations ----------------+++def test_breaking_migration_recommends_reindex_without_actions(monkeypatch):+ """A REINDEX_RECOMMENDED migration informs only; it carries no auto action."""+ fake = (+ Migration(1, UpgradeTier.COMPATIBLE, "baseline"),+ Migration(2, UpgradeTier.REINDEX_RECOMMENDED, "graph layout changed"),+ )+ monkeypatch.setattr(registry_mod, "MIGRATIONS", fake)+ verdict = assess({"store_format_version": 1}, current_store_version=2)+ assert verdict.tier == UpgradeTier.REINDEX_RECOMMENDED+ assert verdict.reindex_recommended+ assert verdict.reindex_command # a command is surfaced+ assert verdict.user_notice+ assert not verdict.actions # never auto-run+++def test_tier_is_max_across_spanned_migrations(monkeypatch):+ fake = (+ Migration(1, UpgradeTier.COMPATIBLE, "baseline"),+ Migration(2, UpgradeTier.AUTO, "auto step", UpgradeActionKind.DROP_PARSE_CACHE),+ Migration(3, UpgradeTier.RE_PARSE, "reparse step", UpgradeActionKind.DROP_PARSE_CACHE),+ )+ monkeypatch.setattr(registry_mod, "MIGRATIONS", fake)+ verdict = assess({"store_format_version": 1}, current_store_version=3)+ assert verdict.tier == UpgradeTier.RE_PARSE+ assert len(verdict.summaries) == 2 # the two spanned, not the baseline+++# --- registry helper ------------------------------------------------------+++def test_migrations_between_is_exclusive_inclusive(monkeypatch):+ fake = tuple(Migration(v, UpgradeTier.COMPATIBLE, f"v{v}") for v in (1, 2, 3))+ monkeypatch.setattr(registry_mod, "MIGRATIONS", fake)+ spanned = migrations_between(1, 3)+ assert [m.to_version for m in spanned] == [2, 3]+++# --- stamp ----------------------------------------------------------------+++def test_stamp_writes_version_markers():+ state: dict[str, object] = {}+ stamp(state, package_version="9.9.9")+ assert state["store_format_version"] == STORE_FORMAT_VERSION+ assert state["written_by_version"] == "9.9.9"+++def test_stamp_without_package_version_omits_written_by():+ state: dict[str, object] = {}+ stamp(state, package_version=None)+ assert state["store_format_version"] == STORE_FORMAT_VERSION+ assert "written_by_version" not in state+++# --- apply_auto -----------------------------------------------------------+++class _RecordingContext:+ def __init__(self, fail: bool = False) -> None:+ self.reembedded = False+ self.dropped = False+ self._fail = fail++ async def reembed_vectors(self) -> None:+ if self._fail:+ raise RuntimeError("boom")+ self.reembedded = True++ def drop_parse_cache(self) -> None:+ self.dropped = True+++async def test_apply_auto_dispatches_actions():+ verdict = UpgradeVerdict(+ tier=UpgradeTier.AUTO,+ from_store_version=0,+ to_store_version=1,+ actions=(+ UpgradeAction(UpgradeActionKind.REEMBED_VECTORS, "embedding changed"),+ UpgradeAction(UpgradeActionKind.DROP_PARSE_CACHE, "parser changed"),+ ),+ )+ ctx = _RecordingContext()+ ran = await apply_auto(verdict, ctx)+ assert ctx.reembedded and ctx.dropped+ assert set(ran) == {UpgradeActionKind.REEMBED_VECTORS, UpgradeActionKind.DROP_PARSE_CACHE}+++async def test_apply_auto_never_raises_on_failure():+ verdict = UpgradeVerdict(+ tier=UpgradeTier.AUTO,+ from_store_version=0,+ to_store_version=1,+ actions=(UpgradeAction(UpgradeActionKind.REEMBED_VECTORS, "x"),),+ )+ ctx = _RecordingContext(fail=True)+ ran = await apply_auto(verdict, ctx) # must not raise+ assert ran == []diff --git a/tests/unit/upgrade/test_parse_cache_decoupling.py b/tests/unit/upgrade/test_parse_cache_decoupling.pynew file mode 100644index 000000000..206a27bfe--- /dev/null+++ b/tests/unit/upgrade/test_parse_cache_decoupling.py@@ -0,0 +1,35 @@+"""The parse-cache fingerprint must be decoupled from the package version.++An ordinary release bumps ``repowise.core.__version__`` but ships no parser+change; that must NOT invalidate a user's parse cache. A real parser change+bumps ``PARSER_SCHEMA_VERSION``, which MUST invalidate it.+"""++from __future__ import annotations++import repowise.core.ingestion.parse_cache as pc+import repowise.core.upgrade.version as ver+++def _fresh_fingerprint() -> str:+ pc.parser_fingerprint.cache_clear()+ return pc.parser_fingerprint()+++def test_package_version_change_keeps_cache_warm(monkeypatch):+ before = _fresh_fingerprint()+ monkeypatch.setattr("repowise.core.__version__", "999.0.0", raising=False)+ after = _fresh_fingerprint()+ assert before == after, "package version must not affect the parse fingerprint"+++def test_parser_schema_version_change_invalidates_cache(monkeypatch):+ before = _fresh_fingerprint()+ monkeypatch.setattr(ver, "PARSER_SCHEMA_VERSION", ver.PARSER_SCHEMA_VERSION + 1)+ after = _fresh_fingerprint()+ assert before != after, "parser schema bump must change the fingerprint"+++def test_fingerprint_is_stable_across_calls():+ pc.parser_fingerprint.cache_clear()+ assert pc.parser_fingerprint() == pc.parser_fingerprint()