@hupan56/wlkj 2.6.0 → 2.7.0

package/templates/qoder/scripts/common/graph_traverse.py

@@ -0,0 +1,533 @@
+# -*- coding: utf-8 -*-
+"""
+In-memory graph traversal engine for the QODER knowledge graph.
+
+Loads the existing JSON indexes into an adjacency structure and supports
+multi-hop BFS queries that no single index can answer alone:
+
+  - impact(endpoint)  → "改这个接口影响哪些页面/按钮/模块?"
+  - context360(symbol) → "这个符号的360度视图: 谁调用它/它调用谁/属于哪"
+
+This is the "上层工程 U1" piece: turning write-only data (trace-chain,
+code-api, prd-index) into live queryable knowledge. No graph database needed
+— a few thousand entities traverse in milliseconds in pure Python dicts.
+
+Design constraints (from the deep-thinking rounds):
+  - relations loaded on-demand, never slowing existing index loads
+  - degrades gracefully when indexes are missing (new project / partial build)
+  - output is AI-readable compact text, not raw JSON
+"""
+import json
+import os
+import re
+from collections import defaultdict
+
+
+def _load(path):
+    """Load JSON if exists, else return None."""
+    if path and os.path.isfile(path):
+        try:
+            return json.load(open(path, encoding='utf-8'))
+        except Exception:
+            return None
+    return None
+
+
+class CodeGraph:
+    """In-memory graph built from the existing JSON indexes.
+
+    Indexes consumed:
+      trace-chain.json  → edges: button @click → API endpoint
+      code-api.json     → endpoint → Java controller file
+      ui-modules.json   → module names (Chinese labels)
+      prd-index.json    → PRD features + related code
+      ui-style.json     → page → module (via vue_file path)
+    """
+
+    def __init__(self, index_dir):
+        self.index_dir = index_dir
+        self._loaded = False
+        self._duckdb_con = None
+        # Adjacency / lookup structures (built lazily on first query)
+        self.endpoint_to_traces = {}      # {endpoint: [trace, ...]}
+        self.endpoint_to_controller = {}  # {endpoint: controller_file}
+        self.vue_to_module = {}           # {vue_path: module_cn}
+        self.prd_features = {}            # {feature_kw: prd_info}
+        self.tests_by_package = {}        # {package_prefix: [test, ...]} (E1)
+        self.tests_by_dep = {}            # {dep_class: [test, ...]} (E1)
+        # Try DuckDB backend (preferred over JSON)
+        self._try_duckdb()
+
+    def _try_duckdb(self):
+        """Try to connect to kg.duckdb as preferred backend."""
+        db_path = os.path.join(self.index_dir, 'kg.duckdb')
+        if not os.path.isfile(db_path):
+            return
+        try:
+            import duckdb
+            con = duckdb.connect(db_path, read_only=True)
+            tables = con.execute(
+                "SELECT name FROM sqlite_master WHERE type='table'"
+            ).fetchall()
+            if 'entities' in {t[0] for t in tables}:
+                self._duckdb_con = con
+        except Exception:
+            pass
+
+    def _ensure_loaded(self):
+        if self._loaded:
+            return
+        self._loaded = True
+
+        # 1. trace-chain → reverse map (endpoint → who calls it)
+        tc = _load(os.path.join(self.index_dir, 'trace-chain.json'))
+        if tc:
+            for t in tc.get('traces', []):
+                ep = t.get('endpoint')
+                if ep and ep != 'None':
+                    self.endpoint_to_traces.setdefault(ep, []).append(t)
+
+        # 2. code-api → endpoint → controller
+        api = _load(os.path.join(self.index_dir, 'code-api.json'))
+        if api:
+            self.endpoint_to_controller = dict(api)
+
+        # 3. ui-modules → module dir → cn name (for page→module resolution)
+        mi = _load(os.path.join(self.index_dir, 'ui-modules.json'))
+        self._module_dirs = {}
+        if mi:
+            for proj, mods in mi.get('projects', {}).items():
+                for m in mods:
+                    self._module_dirs[m['dir'].lower()] = m['cn']
+
+        # 4. prd-index → feature keywords
+        pi = _load(os.path.join(self.index_dir, 'prd-index.json'))
+        if pi:
+            for prd_file, info in pi.items():
+                for feat in (info.get('features') or []):
+                    self.prd_features[feat.lower()] = {
+                        'prd': prd_file, 'title': info.get('title', ''),
+                    }
+
+        # 5. test-assertions → index by injected dependency + package (E1 layer)
+        ta = _load(os.path.join(self.index_dir, 'test-assertions.json'))
+        if ta:
+            for t in ta.get('tests', []):
+                # by dependency class (for JOIN to production code)
+                for dep in t.get('injected_deps', []):
+                    self.tests_by_dep.setdefault(dep, []).append(t)
+                # by package (for module-level JOIN)
+                pkg = t.get('package', '')
+                if pkg:
+                    # group by last 2 package segments (e.g. asset.asset)
+                    parts = pkg.split('.')
+                    key = '.'.join(parts[-2:]) if len(parts) >= 2 else pkg
+                    self.tests_by_package.setdefault(key, []).append(t)
+
+        # 6. relations.json → unified edge table (E3: connects all 6 layers)
+        self.relations = _load(os.path.join(self.index_dir, 'relations.json')) or {}
+        self.rel_edges = self.relations.get('edges', {}) if self.relations else {}
+        # Pre-compute controller → tests lookup from relations
+        self.controller_to_tests = self.rel_edges.get('controller_to_tests', {})
+
+    def _resolve_module(self, vue_file):
+        """Infer the Chinese module name from a Vue file path."""
+        parts = vue_file.replace('\\', '/').lower().split('/views/')
+        if len(parts) < 2:
+            return None
+        after_views = parts[1].split('/')[0]  # e.g. "veh", "hr", "maintenance"
+        return self._module_dirs.get(after_views, after_views)
+
+    def _match_endpoint(self, query):
+        """Find all known endpoints that match the query (exact or prefix)."""
+        self._ensure_loaded()
+        # Exact match
+        if query in self.endpoint_to_traces:
+            return [query]
+        if query in self.endpoint_to_controller:
+            return [query]
+        # Prefix / substring match
+        matches = set()
+        for ep in self.endpoint_to_traces:
+            if query in ep or ep in query:
+                matches.add(ep)
+        for ep in self.endpoint_to_controller:
+            if query in ep or ep in query:
+                matches.add(ep)
+        return sorted(matches)
+
+    def impact(self, query, depth=2):
+        """'改 query 影响谁?' — BFS from endpoint outward.
+
+        Uses DuckDB (preferred) or JSON fallback.
+        """
+        # DuckDB fast path
+        if self._duckdb_con:
+            return self._impact_duckdb(query)
+
+        self._ensure_loaded()
+        endpoints = self._match_endpoint(query)
+        if not endpoints:
+            return None
+
+        lines = []
+        lines.append('## 影响分析: {}'.format(query))
+        lines.append('匹配到 {} 个端点:'.format(len(endpoints)))
+
+        all_pages = set()
+        all_modules = set()
+        all_buttons = []
+
+        for ep in endpoints:
+            lines.append('')
+            lines.append('### {}'.format(ep))
+
+            # Controller
+            ctrl = self.endpoint_to_controller.get(ep)
+            if ctrl:
+                ctrl_name = ctrl.split('/')[-1]
+                lines.append('  后端: {}'.format(ctrl_name))
+
+            # Traces (who calls this endpoint)
+            traces = self.endpoint_to_traces.get(ep, [])
+            if traces:
+                lines.append('  前端调用 ({}处):'.format(len(traces)))
+                for t in traces[:8]:
+                    vue = t.get('vue_file', '').split('src/views/')[-1] if 'src/views/' in t.get('vue_file', '') else t.get('vue_file', '')
+                    btn = t.get('button', '?')
+                    handler = t.get('handler', '?')
+                    conf = t.get('confidence', '?')
+                    lines.append('    [{}] {} → {} ({})'.format(btn, vue, handler, conf))
+                    all_pages.add(vue)
+                    all_buttons.append(btn)
+                    mod = self._resolve_module(t.get('vue_file', ''))
+                    if mod:
+                        all_modules.add(mod)
+            else:
+                lines.append('  前端调用: 无 trace 记录 (可能未被前端直接调用, 或 trace 未覆盖)')
+
+        # Summary
+        lines.append('')
+        lines.append('### 影响摘要')
+        lines.append('  受影响页面: {} 个'.format(len(all_pages)))
+        lines.append('  受影响模块: {}'.format(', '.join(sorted(all_modules)) if all_modules else '未识别'))
+        lines.append('  涉及操作: {}'.format(', '.join(sorted(set(all_buttons))) if all_buttons else '无'))
+
+        # Existing test coverage (E3: controller→tests edge from relations.json)
+        affected_controllers = set()
+        for ep in endpoints:
+            ctrl = self.endpoint_to_controller.get(ep, '')
+            if ctrl:
+                affected_controllers.add(ctrl.split('/')[-1].replace('.java', ''))
+
+        relevant_tests = []
+        # E3 precise path: controller → tests (from relations.json)
+        for ctrl in affected_controllers:
+            for t in self.controller_to_tests.get(ctrl, []):
+                relevant_tests.append(t)
+        # Fallback: module/package matching if relations didn't connect
+        if not relevant_tests:
+            for mod in all_modules:
+                for pkg_key, tests in self.tests_by_package.items():
+                    if mod and mod in pkg_key.lower():
+                        relevant_tests.extend(tests)
+        if relevant_tests:
+            seen = set()
+            unique_tests = []
+            for t in relevant_tests:
+                key = t.get('test', '') or t.get('method', '') or str(t)
+                if key not in seen:
+                    seen.add(key)
+                    unique_tests.append(t)
+            lines.append('')
+            lines.append('### 已有测试覆盖 ({}个)'.format(len(unique_tests)))
+            for t in unique_tests[:5]:
+                # Handle both relations format ({test, dep, assertions}) and
+                # test-assertions format ({class, method, injected_deps, assertions})
+                name = t.get('test', '') or '%s.%s' % (t.get('class', ''), t.get('method', ''))
+                deps = t.get('dep', '') or ', '.join(t.get('injected_deps', [])[:3])
+                asserts = ', '.join(t.get('assertions', [])[:3])
+                lines.append('  {} — 依赖[{}] 断言[{}]'.format(name, deps, asserts))
+            lines.append('  → 改完后可跑这些测试做回归验证')
+        else:
+            lines.append('')
+            lines.append('### 已有测试覆盖: 无 (该模块暂无自动化测试, 改动需手动验证)')
+
+        lines.append('')
+        lines.append('  ⚠️ 开发建议: 改完上述接口后, 重点回归以上页面的按钮功能')
+
+        return '\n'.join(lines)
+
+    def context360(self, query):
+        """'query 的360度视图' — 聚合所有索引中关于它的信息。
+
+        Works for: endpoint, api function name, or Vue file path fragment.
+        """
+        self._ensure_loaded()
+        lines = []
+        lines.append('## 360° 视图: {}'.format(query))
+
+        # Endpoint matches
+        endpoints = self._match_endpoint(query)
+        if endpoints:
+            lines.append('')
+            lines.append('### 端点 ({}个)'.format(len(endpoints)))
+            for ep in endpoints[:5]:
+                ctrl = self.endpoint_to_controller.get(ep, '?')
+                traces = self.endpoint_to_traces.get(ep, [])
+                lines.append('  {} → {} (前端{}处调用)'.format(
+                    ep, ctrl.split('/')[-1] if ctrl != '?' else '?', len(traces)))
+
+        # API function matches (from trace-chain api_functions)
+        tc = _load(os.path.join(self.index_dir, 'trace-chain.json'))
+        if tc:
+            api_fns = tc.get('api_functions', {})
+            fn_matches = {k: v for k, v in api_fns.items() if query.lower() in k.lower()}
+            if fn_matches:
+                lines.append('')
+                lines.append('### API 函数 ({}个)'.format(len(fn_matches)))
+                for fn, info in list(fn_matches.items())[:5]:
+                    lines.append('  {} → {} {}'.format(fn, info.get('url', '?'), info.get('verb', '?')))
+
+        # Trace matches (by handler name)
+        if tc:
+            handler_traces = [t for t in tc.get('traces', [])
+                              if query.lower() in t.get('handler', '').lower()]
+            if handler_traces:
+                lines.append('')
+                lines.append('### 前端处理器 ({}处)'.format(len(handler_traces)))
+                for t in handler_traces[:5]:
+                    vue = t.get('vue_file', '').split('src/views/')[-1] if 'src/views/' in t.get('vue_file', '') else '?'
+                    lines.append('  {} @ {} → {} ({})'.format(
+                        t.get('handler'), vue, t.get('endpoint', '?'), t.get('confidence', '?')))
+
+        # PRD references
+        prd_hits = {k: v for k, v in self.prd_features.items() if query.lower() in k}
+        if prd_hits:
+            lines.append('')
+            lines.append('### 关联PRD ({}个)'.format(len(prd_hits)))
+            for feat, info in list(prd_hits.items())[:3]:
+                lines.append('  {} — {} ({})'.format(feat, info['title'], info['prd']))
+
+        if len(lines) <= 2:
+            return None
+        return '\n'.join(lines)
+
+    def coverage_matrix(self):
+        """功能×测试覆盖矩阵 — 哪些功能有测试, 哪些是空白?
+
+        Uses DuckDB SQL (preferred) or entity-registry JSON (fallback).
+        Returns AI-readable text showing each feature's coverage status.
+        """
+        # DuckDB fast path: one SQL query
+        if self._duckdb_con:
+            return self._coverage_matrix_duckdb()
+        self._ensure_loaded()
+        er = _load(os.path.join(self.index_dir, 'entity-registry.json'))
+        if not er:
+            return 'entity-registry.json 不存在, 请先运行 build_entity_registry.py'
+
+        features = er.get('feature_adjacency', {})
+        entities = er.get('entities', {})
+
+        lines = ['## 功能×测试覆盖矩阵', '']
+        lines.append('| 功能 | 端点 | 按钮操作 | 测试 | 覆盖状态 |')
+        lines.append('|------|------|---------|------|---------|')
+
+        # Sort by endpoint count descending
+        sorted_feats = sorted(features.items(),
+                              key=lambda x: -len(x[1].get('endpoints', [])))
+
+        for feat_id, adj in sorted_feats:
+            cn = entities.get(feat_id, {}).get('cn', feat_id)
+            ep_count = len(adj.get('endpoints', []))
+            btn_count = len(adj.get('buttons', []))
+            test_count = len(adj.get('tests', []))
+
+            if ep_count == 0 and btn_count == 0:
+                status = '⚠️ 无端点无按钮(可能是纯展示页)'
+            elif test_count == 0:
+                status = '🔴 无测试覆盖'
+            elif test_count < 3:
+                status = '🟡 测试不足(%d)' % test_count
+            else:
+                status = '🟢 有测试(%d)' % test_count
+
+            lines.append('| %s | %d | %d | %d | %s |' % (
+                cn, ep_count, btn_count, test_count, status))
+
+        # Summary
+        total_feats = len(sorted_feats)
+        no_test = sum(1 for adj in features.values()
+                      if len(adj.get('tests', [])) == 0
+                      and len(adj.get('endpoints', [])) > 0)
+        lines.append('')
+        lines.append('**总计**: %d 功能, %d 有端点但无测试 (🔴 空白)' % (total_feats, no_test))
+        lines.append('')
+        lines.append('⚠️ 无测试的功能是回归测试的盲区, 优先补测试')
+
+        return '\n'.join(lines)
+
+    def feature_overview(self, query=''):
+        """功能概览: 一个功能的完整画像 (端点+按钮+测试+页面)."""
+        self._ensure_loaded()
+        er = _load(os.path.join(self.index_dir, 'entity-registry.json'))
+        if not er:
+            return 'entity-registry.json 不存在'
+
+        entities = er.get('entities', {})
+        features = er.get('feature_adjacency', {})
+
+        # Resolve query to feature entity ID (via alias resolution)
+        q_lower = query.lower()
+        target_feat = None
+        for fid, ent in entities.items():
+            if ent['type'] != 'FEATURE':
+                continue
+            if q_lower in [a.lower() for a in ent['aliases']]:
+                target_feat = fid
+                break
+
+        if not target_feat:
+            # Fuzzy match
+            for fid, ent in entities.items():
+                if ent['type'] != 'FEATURE':
+                    continue
+                if q_lower in ent.get('canonical', '').lower() or q_lower in ent.get('cn', '').lower():
+                    target_feat = fid
+                    break
+
+        if not target_feat:
+            return '未找到功能 "%s"。可用功能: %s' % (
+                query, ', '.join(ent['cn'] for ent in entities.values()
+                                 if ent['type'] == 'FEATURE')[:200])
+
+        ent = entities[target_feat]
+        adj = features.get(target_feat, {})
+        lines = ['## 功能画像: %s (%s)' % (ent['cn'], ent['canonical'])]
+        lines.append('  别名: %s' % ', '.join(ent['aliases'][:8]))
+        lines.append('')
+        lines.append('### 端点 (%d)' % len(adj.get('endpoints', [])))
+        for eid in adj.get('endpoints', [])[:8]:
+            ep = entities.get(eid, {})
+            lines.append('  %s → %s' % (ep.get('canonical', eid),
+                                        ep.get('properties', {}).get('controller', '?')))
+        lines.append('')
+        lines.append('### 按钮操作 (%d)' % len(adj.get('buttons', [])))
+        btn_texts = set()
+        for eid in adj.get('buttons', [])[:20]:
+            btn = entities.get(eid, {})
+            txt = btn.get('properties', {}).get('button_text', '')
+            if txt:
+                btn_texts.add(txt)
+        lines.append('  操作: %s' % ', '.join(sorted(btn_texts)[:15]))
+        lines.append('')
+        lines.append('### 测试 (%d)' % len(adj.get('tests', [])))
+        for eid in adj.get('tests', [])[:5]:
+            test = entities.get(eid, {})
+            lines.append('  %s — 断言[%s]' % (
+                test.get('canonical', eid),
+                ', '.join(test.get('properties', {}).get('assertions', [])[:3])))
+
+        return '\n'.join(lines)
+
+    # ── DuckDB backend methods (preferred when kg.duckdb exists) ──
+
+    def _coverage_matrix_duckdb(self):
+        """Coverage matrix via single SQL query on DuckDB."""
+        con = self._duckdb_con
+        rows = con.execute("""
+            SELECT e.cn,
+                   COUNT(DISTINCT CASE WHEN ed.edge_type='has_endpoint' THEN ed.to_id END) as eps,
+                   COUNT(DISTINCT CASE WHEN ed.edge_type='has_button' THEN ed.to_id END) as btns,
+                   COUNT(DISTINCT CASE WHEN ed.edge_type='has_test' THEN ed.to_id END) as tests
+            FROM entities e
+            LEFT JOIN edges ed ON ed.from_id = e.id
+            WHERE e.type = 'FEATURE'
+            GROUP BY e.id, e.cn
+            HAVING COUNT(DISTINCT CASE WHEN ed.edge_type='has_endpoint' THEN ed.to_id END) > 0
+                OR COUNT(DISTINCT CASE WHEN ed.edge_type='has_button' THEN ed.to_id END) > 0
+            ORDER BY eps DESC
+        """).fetchall()
+
+        lines = ['## 功能x测试覆盖矩阵', '']
+        lines.append('| 功能 | 端点 | 按钮 | 测试 | 状态 |')
+        lines.append('|------|------|------|------|------|')
+        no_test = 0
+        for cn, eps, btns, tests in rows:
+            status = '无测试' if tests == 0 else '有%d' % tests
+            if tests == 0:
+                no_test += 1
+            lines.append('| %s | %d | %d | %d | %s |' % (cn, eps, btns, tests, status))
+        lines.append('')
+        lines.append('总计: %d 功能, %d 无测试' % (len(rows), no_test))
+        return '\n'.join(lines)
+
+    def _impact_duckdb(self, query):
+        """Impact analysis via DuckDB: endpoint -> buttons + controller + tests."""
+        con = self._duckdb_con
+        rows = con.execute("""
+            SELECT id FROM entities
+            WHERE type = 'ENDPOINT'
+              AND (LOWER(canonical) LIKE ? OR LOWER(id) LIKE ?)
+            LIMIT 30
+        """, ['%' + query.lower() + '%', '%' + query.lower() + '%']).fetchall()
+        if not rows:
+            return None
+
+        endpoint_ids = [r[0] for r in rows]
+        lines = ['## 影响分析: %s (%d端点)' % (query, len(endpoint_ids))]
+        all_pages = set()
+        all_buttons = []
+
+        for eid in endpoint_ids:
+            ep = eid.replace('E:', '')
+            lines.append('')
+            lines.append('### %s' % ep)
+            ctrl = con.execute(
+                "SELECT t.canonical FROM edges e JOIN entities t ON e.to_id=t.id WHERE e.from_id=? AND e.edge_type='handled_by'", [eid]
+            ).fetchone()
+            if ctrl:
+                lines.append('  后端: %s' % ctrl[0])
+            btns = con.execute(
+                "SELECT b.canonical, b.props, b.id FROM edges e JOIN entities b ON e.from_id=b.id WHERE e.to_id=? AND e.edge_type='clicks'", [eid]
+            ).fetchall()
+            if btns:
+                lines.append('  前端调用(%d):' % len(btns))
+                for bc, bp, bid in btns[:6]:
+                    import json as _j
+                    p = _j.loads(bp) if bp else {}
+                    vue = bid.split('B:')[1].split(':')[0] if 'B:' in bid else '?'
+                    lines.append('    [%s] %s -> %s (%s)' % (p.get('button','?'), vue, bc, p.get('confidence','?')))
+                    all_pages.add(vue)
+                    all_buttons.append(p.get('button', ''))
+            else:
+                lines.append('  前端调用: 无trace')
+
+        # Test coverage: endpoint -> controller -> tests (2-hop)
+        placeholders = ','.join(['?'] * len(endpoint_ids))
+        tests = con.execute("""
+            SELECT DISTINCT t.id FROM edges e1
+            JOIN edges e2 ON e2.from_id = e1.to_id
+            JOIN entities t ON e2.to_id = t.id
+            WHERE e1.from_id IN (%s) AND e1.edge_type='handled_by'
+              AND e2.edge_type='tested_by' AND t.type='TEST'
+            LIMIT 10
+        """ % placeholders, endpoint_ids).fetchall()
+
+        lines.append('')
+        lines.append('### 影响摘要')
+        lines.append('  受影响页面: %d' % len(all_pages))
+        lines.append('  涉及操作: %s' % ', '.join(sorted(set(b for b in all_buttons if b))[:15]))
+        if tests:
+            lines.append('')
+            lines.append('### 已有测试(%d)' % len(tests))
+            for tr in tests[:5]:
+                lines.append('  %s' % tr[0].replace('T:', ''))
+            lines.append('  -> 改完可跑这些测试做回归')
+        else:
+            lines.append('')
+            lines.append('### 已有测试: 无')
+        lines.append('')
+        lines.append('  改完上述接口后重点回归以上页面')
+        return '\n'.join(lines)

package/templates/qoder/scripts/common/paths.py

@@ -78,6 +78,95 @@ FILE_DEVELOPER = ".developer"
 FILE_JOURNAL_PREFIX = "journal-"
 
 
+# =============================================================================
+# Index file registry — SINGLE SOURCE OF TRUTH for data/index/ filenames
+# =============================================================================
+# Why this exists: 17 index files used to be flat-named in data/index/ with
+# 4 different naming styles, and two (module-map vs module-index) differed by
+# one word but meant totally different things. Every consumer hardcoded the
+# filename as a string literal. Now all names live here — rename = change once.
+#
+# Naming convention: <category>-<subject>.json
+#   code-   source code layer (search, APIs, stats, dependency graph)
+#   ui-     UI/style layer (page patterns, module names, design fingerprint)
+#   trace-  call-chain (button click → API → controller)
+#   prd-    product requirements
+#   wiki-   semantic module docs
+#   ref-    hand-curated static reference (NOT auto-built)
+# Dotfiles (.meta, .cache) are machine-local bookkeeping.
+
+DATA_INDEX_DIR = PROJECT_ROOT / "data" / "index"
+BUILD_CACHE_DIR = DATA_INDEX_DIR / "_build_cache"  # JSON 中间产物 (构建器写→kg_duckdb读→DuckDB)
+KG_DB_PATH = DATA_INDEX_DIR / "kg.duckdb"  # 知识图谱单文件存储 (消费层唯一查询入口)
+
+INDEX_FILES = {
+    # ── code layer (built by git_sync.py) ──
+    'code_keyword':    'code-keyword.json',      # was code-keyword.json
+    'code_api':        'code-api.json',          # was code-api.json
+    'code_stats':      'code-stats.json',        # was code-stats.json (PROJECT FILE COUNTS)
+    'code_callgraph':  'code-code-callgraph.json',    # was code-callgraph.json
+    # ── UI layer (built by build_style_index.py) ──
+    'ui_style':        'ui-style.json',          # was ui-style.json
+    'ui_style_meta':   'ui-ui-style-meta.json',     # was ui-style-meta.json
+    'ui_modules':      'ui-modules.json',        # was ui-modules.json (BUSINESS MODULE NAMES)
+    # ── call-chain (built by build_style_index.py) ──
+    'trace_chain':     'trace-chain.json',       # was trace-chain.json
+    # ── 浏览器测试锚点 (built/updated by autotest.py learn) ──
+    'test_pages':      'test-pages.json',        # 页面稳定锚点(role/name/placeholder), 团队共享
+    # ── PRD layer (built by git_sync.py) ──
+    'prd_index':       'prd-index.json',         # (name unchanged, already clear)
+    'prd_code_map':    'prd-code-map.json',      # (name unchanged)
+    # ── semantic ──
+    'wiki_index':      'wiki-index.json',        # (name unchanged)
+    # ── static reference (hand-curated, committed to git) ──
+    'ref_vben':        'ref-vben-style.json',    # was ref-vben-style.json
+    'ref_chart':       'ref-chart-style.json',   # was ref-chart-style.json
+    'ref_icon':        'ref-icon.json',          # was ref-icon.json
+    # ── meta / cache (dotfiles, machine-local) ──
+    'meta_index':      '.index-meta.json',       # (name unchanged)
+    'meta_prd_collected': '.prd-collected.json', # (name unchanged)
+    'meta_last_sync':  '.last-sync',             # (name unchanged)
+    'cache_inverted':  '.inverted-cache.json',   # (name unchanged)
+    'cache_file_keys': '.file-keys.json',        # (name unchanged)
+    'meta_req_counter': 'req-counter.json',      # (name unchanged)
+}
+
+# Legacy → new name mapping (for migration + backward-compat lookups)
+INDEX_NAME_MIGRATION = {
+    'code-keyword.json':      'code-keyword.json',
+    'code-api.json':          'code-api.json',
+    'code-stats.json':         'code-stats.json',
+    'code-callgraph.json':          'code-code-callgraph.json',
+    'ui-style.json':        'ui-style.json',
+    'ui-style-meta.json':         'ui-ui-style-meta.json',
+    'ui-modules.json':       'ui-modules.json',
+    'trace-chain.json':        'trace-chain.json',
+    'ref-vben-style.json': 'ref-vben-style.json',
+    'ref-chart-style.json': 'ref-chart-style.json',
+    'ref-icon.json':     'ref-icon.json',
+}
+
+
+def index_path(key: str) -> Path:
+    """Get the full path for an index file by its registry key.
+
+    Usage:  index_path('code_keyword')  →  data/index/code-keyword.json
+    """
+    name = INDEX_FILES.get(key)
+    if name is None:
+        raise KeyError('Unknown index key: %r (valid: %s)' % (key, sorted(INDEX_FILES)))
+    return DATA_INDEX_DIR / name
+
+
+def resolve_index_name(filename: str) -> str:
+    """Resolve a (possibly legacy) index filename to its current name.
+
+    Falls back to the input unchanged if not in the migration map.
+    Used by load helpers for backward compatibility.
+    """
+    return INDEX_NAME_MIGRATION.get(filename, filename)
+
+
 # =============================================================================
 # Core functions
 # =============================================================================