Remove legacy cache migration and require current index formats

Author: ktappdev

README.md

@@ -122,11 +122,15 @@ Successful LLM responses are saved even if another batch fails. The command
 still exits with an error; rerun without `--force` to request only missing,
 short, or stale entries. `--batch-size` explicitly controls batch size when set.
 
-The cache automatically migrates to version 2 on the next write. Unique legacy
-entries are retained; ambiguous parent/file keys are dropped rather than shared
-between unrelated files. Legacy entries have no context fingerprint, so their
-first online `init` or `sync` refreshes them. Use `--offline` with `init` to migrate
-without LLM requests. Keep the CLI upgraded when sharing these cache files.
+Only version 2 caches and indexes are supported. Older files are rejected;
+there is no migration or synonym-key fallback. For the default paths, rebuild:
+
+```bash
+rm .ctxt/ctx_cache.json
+ctxt init .
+```
+
+Use `ctxt init . --offline` to rebuild without LLM requests.
 
 Use `init` or restart `watch` after adding files, then run `sync` to fill gaps.
 

cache.go

@@ -6,6 +6,8 @@ import (
 	"os"
 )
 
+const currentCacheVersion = 2
+
 type synonymCacheState struct {
 	Version      int               `json:"cache_version"`
 	Entries      SynonymResponse   `json:"entries"`
@@ -18,7 +20,7 @@ func LoadSynonymCache(path string) (SynonymResponse, error) {
 }
 
 func loadSynonymCacheState(path string) (synonymCacheState, error) {
-	state := synonymCacheState{Entries: make(SynonymResponse), Fingerprints: make(map[string]string)}
+	state := synonymCacheState{Version: currentCacheVersion, Entries: make(SynonymResponse), Fingerprints: make(map[string]string)}
 	if path == "" {
 		return state, nil
 	}
@@ -29,20 +31,16 @@ func loadSynonymCacheState(path string) (synonymCacheState, error) {
 	if err != nil {
 		return state, fmt.Errorf("read synonym cache: %w", err)
 	}
-	var fields map[string]json.RawMessage
-	if err := json.Unmarshal(data, &fields); err != nil {
-		return state, fmt.Errorf("parse synonym cache: %w", err)
+	// Decode into a fresh value so a missing version is rejected.
+	var decoded synonymCacheState
+	if err := json.Unmarshal(data, &decoded); err != nil {
+		return state, fmt.Errorf("parse synonym cache: %w; remove the cache file and run ctxt init", err)
 	}
-	if version, ok := fields["cache_version"]; ok && len(version) > 0 && version[0] != '[' {
-		if err := json.Unmarshal(data, &state); err != nil {
-			return state, fmt.Errorf("parse synonym cache: %w", err)
-		}
-		if state.Version != 2 {
-			return state, fmt.Errorf("unsupported synonym cache version %d", state.Version)
-		}
-	} else if err := json.Unmarshal(data, &state.Entries); err != nil {
-		return state, fmt.Errorf("parse synonym cache: %w", err)
+	if decoded.Version != currentCacheVersion {
+		return state, fmt.Errorf("unsupported synonym cache version %d; remove the cache file and run ctxt init", decoded.Version)
 	}
+	state = decoded
+
 	if state.Entries == nil {
 		state.Entries = make(SynonymResponse)
 	}
@@ -59,7 +57,7 @@ func saveSynonymCacheState(path string, state synonymCacheState) error {
 	if path == "" {
 		return nil
 	}
-	state.Version = 2
+	state.Version = currentCacheVersion
 	data, err := json.MarshalIndent(state, "", "  ")
 	if err != nil {
 		return fmt.Errorf("marshal synonym cache: %w", err)
@@ -68,18 +66,8 @@ func saveSynonymCacheState(path string, state synonymCacheState) error {
 }
 
 func SaveSynonymCache(path string, cache SynonymResponse) error {
-	if path == "" {
-		return nil
-	}
 	if cache == nil {
 		cache = make(SynonymResponse)
 	}
-	bytes, err := json.MarshalIndent(cache, "", "  ")
-	if err != nil {
-		return fmt.Errorf("marshal synonym cache: %w", err)
-	}
-	if err := writeFileAtomic(path, append(bytes, '\n'), 0o600); err != nil {
-		return fmt.Errorf("write synonym cache: %w", err)
-	}
-	return nil
+	return saveSynonymCacheState(path, synonymCacheState{Entries: cache})
 }

cache_migration.go

@@ -128,7 +128,6 @@ Examples:
 				SynonymsMin:         flags.SynonymsMin,
 				SynonymsMax:         flags.SynonymsMax,
 				SynonymCache:        cacheState.Entries,
-				CacheVersion:        cacheState.Version,
 				SynonymFingerprints: cacheState.Fingerprints,
 				MaxBatchSize:        cfg.Watch.MaxBatchSize,
 				Endpoint:            llmEndpoint,
@@ -145,7 +144,7 @@ Examples:
 			}
 
 			emitSynonymWarning(result.SynonymError)
-			if err := saveSynonymCacheState(cachePath, synonymCacheState{Version: 2, Entries: result.SynonymCache, Fingerprints: result.SynonymFingerprints}); err != nil {
+			if err := saveSynonymCacheState(cachePath, synonymCacheState{Version: currentCacheVersion, Entries: result.SynonymCache, Fingerprints: result.SynonymFingerprints}); err != nil {
 				return err
 			}
 			if err := SaveContextIndex(outputPath, result.Index); err != nil {

command_init.go

@@ -1,6 +1,7 @@
 package contexting
 
 import (
+	"errors"
 	"fmt"
 	"os"
 	"path/filepath"
@@ -42,7 +43,7 @@ Examples:
   ctxt search-hints "database" --explain        Show score breakdown
   ctxt search-hints "upload" --type files       Files only (no directories)
   ctxt search-hints "config" --limit 20         More results`,
-		Args:  cobra.ExactArgs(1),
+		Args: cobra.ExactArgs(1),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			var absConfigPath string
 			if configPath != "" {
@@ -121,6 +122,9 @@ Examples:
 			if !usedMemory {
 				index, err := LoadContextIndex(indexPath)
 				if err != nil {
+					if !errors.Is(err, os.ErrNotExist) {
+						return err
+					}
 					if useMemory {
 						source = "none"
 						f := true

command_search.go

@@ -90,7 +90,6 @@ Examples:
 				return fmt.Errorf("load synonym cache: %w", err)
 			}
 
-			cacheState = migrateSynonymCache(index.Tree, cacheState)
 			allNames := CollectNamesForLLM(index.Tree)
 			if targetPath != "" {
 				resolved := resolveProjectPath(absRoot, targetPath)

command_sync.go

@@ -67,7 +67,6 @@ type IndexManager struct {
 
 	index        *ContextIndex
 	cache        SynonymResponse
-	cacheVersion int
 	fingerprints map[string]string
 	dirty        bool
 	loaded       bool
@@ -207,19 +206,14 @@ func (m *IndexManager) Bootstrap(ctx context.Context) (IndexStats, error) {
 		return IndexStats{}, err
 	}
 	m.cache = state.Entries
-	m.cacheVersion = state.Version
 	m.fingerprints = state.Fingerprints
 
 	loadedIndex, err := LoadContextIndex(m.outputPath)
 	if err == nil && loadedIndex != nil && loadedIndex.Tree != nil {
 		if absRoot, rootErr := filepath.Abs(m.rootPath); rootErr == nil && loadedIndex.RootPath == absRoot {
-			migrated := state.Version < 2
-			state = migrateSynonymCache(loadedIndex.Tree, state)
-			m.cache = state.Entries
-			m.cacheVersion = state.Version
 			m.index = loadedIndex
 			m.loaded = true
-			m.dirty = migrated
+			m.dirty = false
 
 			// Diff snapshot against filesystem to catch changes made while not running
 			fsState, fsErr := collectFilesystemState(m.rootPath, m.ignored)
@@ -311,7 +305,6 @@ func (m *IndexManager) Bootstrap(ctx context.Context) (IndexStats, error) {
 		SynonymsMin:         m.synonymsMin,
 		SynonymsMax:         m.synonymsMax,
 		SynonymCache:        m.cache,
-		CacheVersion:        m.cacheVersion,
 		SynonymFingerprints: m.fingerprints,
 		MaxBatchSize:        m.maxBatchSize,
 		Endpoint:            m.endpoint,
@@ -323,7 +316,6 @@ func (m *IndexManager) Bootstrap(ctx context.Context) (IndexStats, error) {
 	}
 	m.index = result.Index
 	m.cache = result.SynonymCache
-	m.cacheVersion = 2
 	m.fingerprints = result.SynonymFingerprints
 	m.dirty = true
 	m.loaded = true
@@ -472,7 +464,7 @@ func (m *IndexManager) FlushIfDirty() (bool, error) {
 	if !m.dirty || m.index == nil {
 		return false, nil
 	}
-	if err := saveSynonymCacheState(m.cachePath, synonymCacheState{Version: 2, Entries: m.cache, Fingerprints: m.fingerprints}); err != nil {
+	if err := saveSynonymCacheState(m.cachePath, synonymCacheState{Version: currentCacheVersion, Entries: m.cache, Fingerprints: m.fingerprints}); err != nil {
 		return false, err
 	}
 	if err := SaveContextIndex(m.outputPath, m.index); err != nil {

index_manager.go

@@ -18,7 +18,6 @@ type BuildOptions struct {
 	SynonymsMin         int
 	SynonymsMax         int
 	SynonymCache        SynonymResponse
-	CacheVersion        int
 	SynonymFingerprints map[string]string
 	MaxBatchSize        int
 	Endpoint            string
@@ -87,7 +86,10 @@ func BuildIndex(opts BuildOptions) (*BuildResult, error) {
 	LogInfof("✓ Built tree: %d files, %d directories%s", stats.TotalFiles, stats.TotalDirs, extraMsg)
 
 	names := CollectNamesForLLM(tree)
-	state := migrateSynonymCache(tree, synonymCacheState{Version: opts.CacheVersion, Entries: cloneSynonymMap(opts.SynonymCache), Fingerprints: opts.SynonymFingerprints})
+	state := synonymCacheState{Entries: cloneSynonymMap(opts.SynonymCache), Fingerprints: opts.SynonymFingerprints}
+	if state.Fingerprints == nil {
+		state.Fingerprints = make(map[string]string)
+	}
 	combined := state.Entries
 	// Sequential execution: extract symbols FIRST, then generate synonyms with symbols context
 	var symbolCount int

indexer.go

@@ -117,24 +117,10 @@ func BuildTree(rootPath string, ignored map[string]bool) (*Node, error) {
 	return root, nil
 }
 
-func pathSuffix(fullPath string) string {
-	dir := filepath.Dir(fullPath)
-	base := filepath.Base(fullPath)
-	parent := filepath.Base(dir)
-	// For root-level files, parent is the project directory name (still useful context).
-	// For deeply nested files, parentDir/basename is usually unique enough.
-	return parent + "/" + base
-}
-
-// llmSynonymKey returns the key used for LLM synonym generation and lookup.
-// New indexes use project-relative paths. Legacy nodes retain suffix lookup
-// until their cache is migrated.
-func llmSynonymKey(node *Node) string {
-	if node.SynonymKey != "" {
-		return node.SynonymKey
-	}
+// nodeLexicalName keeps lexical hints focused on the immediate location.
+func nodeLexicalName(node *Node) string {
 	if node.Type == "file" {
-		return pathSuffix(node.FullPath)
+		return filepath.Base(filepath.Dir(node.FullPath)) + "/" + filepath.Base(node.FullPath)
 	}
 	return filepath.Base(node.FullPath)
 }
@@ -150,7 +136,10 @@ func CollectNamesForLLM(tree *Node) []string {
 		if node == tree {
 			return
 		}
-		name := llmSynonymKey(node)
+		name := node.SynonymKey
+		if name == "" {
+			return
+		}
 		if _, ok := seen[name]; ok {
 			return
 		}
@@ -168,7 +157,7 @@ func AssignSynonymsToTree(tree *Node, synonyms SynonymResponse, maxPerNode int)
 			if node == tree {
 				return
 			}
-			node.Synonyms = sanitizeSynonyms(lexicalSynonyms(legacySynonymKey(node)), maxPerNode)
+			node.Synonyms = sanitizeSynonyms(lexicalSynonyms(nodeLexicalName(node)), maxPerNode)
 		})
 		return
 	}
@@ -177,12 +166,12 @@ func AssignSynonymsToTree(tree *Node, synonyms SynonymResponse, maxPerNode int)
 		if node == tree {
 			return
 		}
-		name := llmSynonymKey(node)
+		name := node.SynonymKey
 		combined := make([]string, 0, maxPerNode+4)
 		if syns, ok := synonyms[name]; ok {
 			combined = append(combined, syns...)
 		}
-		combined = append(combined, lexicalSynonyms(legacySynonymKey(node))...)
+		combined = append(combined, lexicalSynonyms(nodeLexicalName(node))...)
 		node.Synonyms = sanitizeSynonyms(combined, maxPerNode)
 	})
 }

node.go

@@ -88,7 +88,7 @@ func upsertNodeByRelPath(root *Node, absRoot string, relPath string, isDir bool,
 		}
 		size = info.Size()
 	}
-	nodeSynonyms := buildNodeSynonyms(filepath.ToSlash(relPath), legacySynonymKey(&Node{FullPath: fullPath, Type: nodeType}), cache, maxSynonyms)
+	nodeSynonyms := buildNodeSynonyms(filepath.ToSlash(relPath), nodeLexicalName(&Node{FullPath: fullPath, Type: nodeType}), cache, maxSynonyms)
 
 	node, ok := parent.Children[name]
 	if !ok {