argo-search 1.0.1 → 2.9.7

package/sub-skills/local-seek/tests/test_pcre2_probe.py

@@ -0,0 +1,136 @@
+#!/usr/bin/env python3
+"""pcre2 判据回归测试（2026-09-27）。
+
+守的缺陷：`pcre2_supported()` 曾用「跑一次匹配看返回码」判定 rg 是否支持 PCRE2：
+
+    proc = run(["rg", "--pcre2", "-e", "x", os.devnull])
+    _pcre2_ok = proc is not None and proc.returncode == 0
+
+`/dev/null` 永远没有匹配，rg 无匹配时返回 1，于是判据恒为 False——本机
+rg 明明带 +pcre2，却永远被判为「未编译 PCRE2」，所有 look-around /
+反向引用查询被拒绝（用户可见的报错：「请简化查询」）。
+
+根因是**判据的观察量与被判定的性质无关**：探测目标的匹配结果说明不了
+二进制是否带某个特性。修法改读 `rg --version` 的 features 行。
+
+这组测试把「返回码语义」钉死：只 mock run() 的返回值，覆盖
+  - features 行含 +pcre2 → True
+  - features 行是 -pcre2 → False
+  - rg 不存在（run 返回 None）→ False
+  - 只判 features 行，不被「匹配有无」影响（原缺陷的形态）
+
+运行：
+  cd ~/.agents/skills/argo
+  python3 -m pytest sub-skills/local-seek/tests/test_pcre2_probe.py -q
+"""
+
+from __future__ import annotations
+
+import subprocess
+import sys
+import unittest
+from pathlib import Path
+from unittest import mock
+
+SCRIPTS = Path(__file__).resolve().parent.parent / "scripts"
+sys.path.insert(0, str(SCRIPTS))
+
+import seek as s  # noqa: E402
+
+
+def _proc(stdout: str, returncode: int = 0):
+    p = mock.Mock()
+    p.stdout = stdout
+    p.returncode = returncode
+    return p
+
+
+class TestPcre2Probe(unittest.TestCase):
+    def setUp(self):
+        # 模块级缓存必须在每个用例前清掉，否则第一个用例的结果会被后续复用
+        self._saved = s._pcre2_ok
+        s._pcre2_ok = None
+        self.addCleanup(lambda: setattr(s, "_pcre2_ok", self._saved))
+
+    def test_features_line_with_pcre2_is_true(self):
+        """正面：features:+pcre2 → 支持（本机 rg 15.0.0 的真实形态）。"""
+        out = "ripgrep 15.0.0 (rev 3a612f88b8)\n\nfeatures:+pcre2\nsimd(compile):+NEON\n"
+        with mock.patch.object(s, "run", return_value=_proc(out)):
+            self.assertTrue(s.pcre2_supported())
+
+    def test_features_line_without_pcre2_is_false(self):
+        """反面：features 行明确是 -pcre2 → 不支持，走 grep 回退。"""
+        out = "ripgrep 13.0.0\n\nfeatures:-pcre2\n"
+        with mock.patch.object(s, "run", return_value=_proc(out)):
+            self.assertFalse(s.pcre2_supported())
+
+    def test_missing_rg_is_false(self):
+        """rg 不存在时 run() 返回 None → False（不得抛异常）。"""
+        with mock.patch.object(s, "run", return_value=None):
+            self.assertFalse(s.pcre2_supported())
+
+    def test_does_not_depend_on_match_result(self):
+        """核心回归：判据不得再依赖「有没有匹配」。
+
+        原缺陷的形态是 `returncode == 0`——把「无匹配(1)」误读成「不支持」。
+        这里给一个**无匹配语义**的返回码 1 但 features 行含 +pcre2，
+        新判据必须仍判 True。若有人把它改回看返回码，本用例会红。
+        """
+        out = "ripgrep 15.0.0\n\nfeatures:+pcre2\n"
+        with mock.patch.object(s, "run", return_value=_proc(out, returncode=1)):
+            self.assertTrue(s.pcre2_supported(),
+                            "判据又依赖返回码了：无匹配(rc=1)被误读成不支持 PCRE2")
+
+    def test_probe_targets_version_not_a_match_run(self):
+        """确认探测命令本身是 --version，而不是「跑一次匹配」。"""
+        captured = {}
+
+        def _fake(cmd, **kwargs):
+            captured["cmd"] = cmd
+            return _proc("ripgrep 15.0.0\nfeatures:+pcre2\n")
+
+        with mock.patch.object(s, "run", side_effect=_fake):
+            s.pcre2_supported()
+        self.assertIn("--version", captured["cmd"],
+                      "探测命令必须是 rg --version（读特性声明），不是匹配探测")
+
+    def test_module_cache_avoids_repeated_probe(self):
+        """缓存语义：只探一次，第二次不再调 run()。"""
+        calls = []
+
+        def _fake(cmd, **kwargs):
+            calls.append(cmd)
+            return _proc("ripgrep 15.0.0\nfeatures:+pcre2\n")
+
+        with mock.patch.object(s, "run", side_effect=_fake):
+            s.pcre2_supported()
+            s.pcre2_supported()
+            s.pcre2_supported()
+        self.assertEqual(len(calls), 1, "模块级缓存失效，重复探测")
+
+
+class TestPcre2EndToEnd(unittest.TestCase):
+    """真机对照：本机 rg 带 +pcre2 时，look-around 查询真的能出结果。
+
+    不断言「一定支持」（别的机器可能没有），而是断言**判据与真机能力一致**：
+    先读 rg --version 拿真值，再要求 pcre2_supported() 与之一致。
+    """
+
+    def test_agrees_with_real_rg(self):
+        try:
+            real = subprocess.run(["rg", "--version"], capture_output=True,
+                                  text=True, timeout=10)
+        except (FileNotFoundError, subprocess.TimeoutExpired):
+            self.skipTest("本机无 rg，跳过真机对照")
+        truth = "+pcre2" in (real.stdout or "")
+        saved = s._pcre2_ok
+        s._pcre2_ok = None
+        try:
+            self.assertEqual(s.pcre2_supported(), truth,
+                             "判据与 rg 自报的特性不一致")
+        finally:
+            s._pcre2_ok = saved
+
+
+if __name__ == "__main__":
+    unittest.main()

package/sub-skills/local-seek/tests/test_rank_pinyin.py

@@ -0,0 +1,77 @@
+#!/usr/bin/env python3
+"""local-seek 文件名相关性排序 + 拼音首字母单测（离线）
+
+覆盖：
+  1. pinyin_initials：中文→拼音首字母（pypinyin 优先 / GB2312 保底）
+  2. _fzf_score：fzf 式文件名评分（smart case / 连续 / 边界 / 全等）
+  3. _file_pinyin_bonus：正向（中文→缩写）与反向（缩写→中文文件名）加分
+  4. _rank_path_results：按相关性 + mtime 排序
+  5. _looks_like_pinyin_abbrev：拼音缩写判定
+
+运行：
+  cd ~/.agents/skills/argo
+  python3.14 -m pytest sub-skills/local-seek/tests/test_rank_pinyin.py -q
+"""
+
+from __future__ import annotations
+
+import sys
+import unittest
+from pathlib import Path
+
+SCRIPTS = Path(__file__).resolve().parent.parent / "scripts"
+sys.path.insert(0, str(SCRIPTS))
+
+import seek as s  # noqa: E402
+
+
+class TestPinyin(unittest.TestCase):
+    def test_zh_initials(self):
+        self.assertEqual(s.pinyin_initials("新建夹"), "xjj")
+
+    def test_non_cjk_kept(self):
+        self.assertIn("report", s.pinyin_initials("report_v2.md"))
+
+    def test_empty(self):
+        self.assertEqual(s.pinyin_initials(""), "")
+
+
+class TestFzfScore(unittest.TestCase):
+    def test_match_boundary(self):
+        self.assertGreater(s._fzf_score("新建夹.pdf", "新"), 0)
+
+    def test_continuous(self):
+        self.assertGreater(s._fzf_score("report_v2.md", "rep"), 0)
+
+    def test_no_match(self):
+        self.assertEqual(s._fzf_score("zzz.txt", "rep"), 0)
+
+    def test_case_insensitive(self):
+        self.assertGreater(s._fzf_score("Report_v2.md", "report"), 0)
+
+
+class TestPinyinBonus(unittest.TestCase):
+    def test_forward(self):
+        self.assertEqual(s._file_pinyin_bonus("新建夹.pdf", "新建夹"), 50)
+
+    def test_reverse(self):
+        self.assertEqual(s._file_pinyin_bonus("新建夹.pdf", "xjj"), 8)
+
+    def test_none(self):
+        self.assertEqual(s._file_pinyin_bonus("other.txt", "xjj"), 0)
+
+
+class TestRank(unittest.TestCase):
+    def test_rank_top_by_relevance(self):
+        r = [("a/zzz.txt", 0, ""), ("b/新建夹.pdf", 0, ""), ("c/report_v2.md", 0, "")]  # noqa: E741
+        ranked = s._rank_path_results(r, "新")
+        self.assertEqual(ranked[0][0], "b/新建夹.pdf")
+
+    def test_abbrev_look(self):
+        self.assertTrue(s._looks_like_pinyin_abbrev("xjj"))
+        self.assertFalse(s._looks_like_pinyin_abbrev("新"))
+        self.assertFalse(s._looks_like_pinyin_abbrev("report"))
+
+
+if __name__ == "__main__":
+    unittest.main()

package/sub-skills/local-seek/tests/test_regression_20261003.py

@@ -0,0 +1,169 @@
+#!/usr/bin/env python3
+"""2026-10-03 审计轮回归测试：四类假阴性 + run_query 契约 + timeout 下传。
+
+守的四个实测缺陷（全部先在真机复现再修）：
+  1. run_query 目录不存在分支 print + 裸 return 1，违反 (text, rc) 契约，
+     MCP/include-local 进程内调用方解包直接 TypeError。
+  2. --since/--until 在 max 截断之后过滤：旧文件占满截断池，新命中被吃掉
+     （实测 20 个新文件只报出 8 个）。
+  3. build_patterns 中文分支不拆英文多词：「性能 asyncio tutorial」的英文段
+     整段化作固定短语，单词条目全部漏掉（eb0ed38 只修了纯英文分支）。
+  4. --scope doc 把 md/txt 从 exts 减掉，文档场景恰好漏掉最常搜的笔记。
+
+运行：
+  cd ~/.agents/skills/argo
+  python3 -m pytest sub-skills/local-seek/tests/test_regression_20261003.py -q
+"""
+
+from __future__ import annotations
+
+import io
+import json
+import os
+import sys
+import tempfile
+import unittest
+from contextlib import redirect_stdout
+from pathlib import Path
+from unittest import mock
+
+SCRIPTS = Path(__file__).resolve().parent.parent / "scripts"
+sys.path.insert(0, str(SCRIPTS))
+
+import seek as s  # noqa: E402
+
+
+def _run_main(argv):
+    """跑 seek.main()，捕获 stdout，返回 (exit_code, stdout)。"""
+    with mock.patch.object(sys, "argv", ["seek.py"] + argv):
+        buf = io.StringIO()
+        try:
+            with redirect_stdout(buf):
+                code = s.main()
+        except SystemExit as e:
+            code = e.code or 0
+    return code or 0, buf.getvalue()
+
+
+class TestBuildPatterns(unittest.TestCase):
+    """中英混排与纯英文分词（缺陷 3）。"""
+
+    def test_mixed_cjk_english_splits_words(self):
+        patterns, fixed = s.build_patterns("性能 asyncio tutorial")
+        self.assertIn("asyncio", patterns, "英文段必须按词拆开")
+        self.assertIn("tutorial", patterns)
+        self.assertIn("性能", patterns)
+        self.assertTrue(fixed)
+
+    def test_pure_english_multiword_unchanged(self):
+        patterns, _ = s.build_patterns("Python asyncio tutorial")
+        self.assertEqual(patterns, ["Python", "asyncio", "tutorial"])
+
+    def test_space_never_a_pattern(self):
+        patterns, _ = s.build_patterns("樯橹 灰飞烟灭")
+        self.assertNotIn("", patterns)
+        self.assertNotIn(" ", patterns)
+
+    def test_cjk_2gram_extension_kept(self):
+        patterns, _ = s.build_patterns("数据抓取")
+        self.assertIn("数据抓取", patterns)
+        self.assertIn("抓取", patterns)
+
+
+class TestSinceFilterBeforeTruncation(unittest.TestCase):
+    """--since 过滤必须发生在截断之前（缺陷 2，真实 rg 端到端）。"""
+
+    def test_new_files_not_swallowed_by_old(self):
+        if not s.tool_exists("rg"):
+            self.skipTest("本机无 rg")
+        with tempfile.TemporaryDirectory() as tmp:
+            ancient = 900000000  # 1998 年，稳落任何时间窗之外
+            for i in range(40):
+                p = Path(tmp) / f"old_{i:02d}.txt"
+                p.write_text("目标词命中 here\n")
+                os.utime(p, (ancient, ancient))
+            for i in range(20):
+                (Path(tmp) / f"new_{i:02d}.txt").write_text("目标词命中 here\n")
+            code, out = _run_main(
+                ["目标词", "--path", tmp, "--since", "1d", "--max", "30", "--json"])
+            self.assertEqual(code, 0)
+            self.assertEqual(json.loads(out)["count"], 20,
+                             "20 个新文件全部在窗口内，一个都不能被旧文件挤掉")
+
+    def test_no_window_returns_all(self):
+        if not s.tool_exists("rg"):
+            self.skipTest("本机无 rg")
+        with tempfile.TemporaryDirectory() as tmp:
+            for i in range(35):
+                (Path(tmp) / f"f_{i:02d}.txt").write_text("目标词命中 here\n")
+            code, out = _run_main(
+                ["目标词", "--path", tmp, "--max", "30", "--json"])
+            self.assertEqual(json.loads(out)["count"], 30)
+
+
+class TestScopeDocIncludesMd(unittest.TestCase):
+    """--scope doc 必须搜到 md（缺陷 4）。"""
+
+    def test_md_hit_in_doc_scope(self):
+        if not s.tool_exists("rg"):
+            self.skipTest("本机无 rg")
+        with tempfile.TemporaryDirectory() as tmp:
+            (Path(tmp) / "notes.md").write_text("检索词在这里\n")
+            code, out = _run_main(
+                ["检索词", "--path", tmp, "--scope", "doc", "--json"])
+            self.assertEqual(code, 0, f"--scope doc 应命中 md，输出：{out}")
+            data = json.loads(out)
+            self.assertTrue(any("notes.md" in r["path"] for r in data["results"]))
+
+
+class TestRunQueryContract(unittest.TestCase):
+    """run_query 必须始终返回 (text, rc)（缺陷 1）。"""
+
+    def test_nonexistent_dir_returns_tuple(self):
+        result = s.run_query(["x", "--path", "/nonexistent-seek-test-xyz"])
+        self.assertIsInstance(result, tuple, "返回裸 int 会让进程内调用方解包崩溃")
+        text, rc = result
+        self.assertIsInstance(text, str)
+        self.assertEqual(rc, 1)
+        self.assertIn("目录不存在", text)
+
+    def test_cli_still_prints_message(self):
+        code, out = _run_main(["x", "--path", "/nonexistent-seek-test-xyz"])
+        self.assertEqual(code, 1)
+        self.assertIn("目录不存在", out)
+
+
+class TestTimeoutDownpass(unittest.TestCase):
+    """structural/git 路径必须把 time_budget 下传给 run（缺陷 5）。"""
+
+    def test_structural_passes_timeout(self):
+        captured = {}
+        def fake_run(cmd, timeout=None, **kw):
+            captured["timeout"] = timeout
+            proc = mock.Mock()
+            proc.returncode = 1  # 无命中
+            proc.stdout = ""
+            return proc
+        with mock.patch.object(s, "run", side_effect=fake_run):
+            s.structural_search("裸except", "/tmp", [], 5, timeout=5.5)
+        self.assertEqual(captured.get("timeout"), 5.5,
+                         "structural_search 必须把 timeout 传给 run")
+
+    def test_git_log_passes_timeout(self):
+        captured = {}
+        def fake_run(cmd, timeout=None, **kw):
+            captured["timeout"] = timeout
+            proc = mock.Mock()
+            proc.returncode = 1
+            proc.stdout = ""
+            return proc
+        with tempfile.TemporaryDirectory() as tmp:
+            f = Path(tmp) / "a.txt"
+            f.write_text("x\n")
+            with mock.patch.object(s, "run", side_effect=fake_run):
+                s.git_log(str(f), timeout=7.5)
+        self.assertEqual(captured.get("timeout"), 7.5)
+
+
+if __name__ == "__main__":
+    unittest.main()

package/sub-skills/local-seek/tests/test_regression_20261006.py

@@ -0,0 +1,146 @@
+#!/usr/bin/env python3
+"""2026-10-06 性能轮回归测试：噪声档判定去 syscall + read_lines 单遍读取。
+
+实测背景（cProfile，Documents/GPT 搜 "import" --count，8930 个文件）：
+    _is_noise_path 独占 1.52s / 1.91s（80%），内含 35727 次 posix.getcwd、
+    103266 次 posix.lstat、35720 次 realpath。根因是每行都做
+    `Path(fp).resolve().relative_to(Path(root).resolve())`——resolve() 对每个
+    路径段 lstat 且反复 getcwd；而 _apply_noise_floor 还把根 resolve 了两遍、
+    每行判了两遍。
+
+修法：纯字符串归一化（normpath + 前缀比较），根只算一次、每行只判一次，
+全程零 syscall。本文件锁定两件事：
+  1. 语义不变——相对/绝对根、根自己叫 tests/、repos/、日期归档、越界路径
+     的判定结果与原实现一致；
+  2. 不得回退到 syscall——_is_noise_path 再调 Path.resolve / realpath / lstat
+     即报红（这是本轮性能收益的守门用例，比计时断言稳定）。
+
+read_lines 原实现先 open 数行、再 open 读区间（同一文件开两遍，大文件 IO
+翻倍），改为单遍流式；本文件锁定区间/越界/空文件三种行为不变。
+
+运行：
+  cd ~/.agents/skills/argo
+  python3 -m pytest sub-skills/local-seek/tests/test_regression_20261006.py -q
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+import tempfile
+import unittest
+from pathlib import Path
+from unittest import mock
+
+SCRIPTS = Path(__file__).resolve().parent.parent / "scripts"
+sys.path.insert(0, str(SCRIPTS))
+
+import seek as s  # noqa: E402
+
+
+class TestNoisePathSemantics(unittest.TestCase):
+    """去 syscall 之后，噪声档判定语义必须与原实现逐条一致。"""
+
+    def test_root_named_tests_is_not_noise(self):
+        # 搜索根自己叫 tests/ 时整棵树不得被判噪声（原实现的核心理由）
+        self.assertFalse(s._is_noise_path("/x/tests/a.py", "/x/tests"))
+
+    def test_src_under_root_is_clean(self):
+        self.assertFalse(s._is_noise_path("/x/src/app.py", "/x"))
+
+    def test_repos_under_root_is_noise(self):
+        self.assertTrue(s._is_noise_path("/x/repos/lib.py", "/x"))
+
+    def test_date_archive_dir_is_noise(self):
+        self.assertTrue(s._is_noise_path("/x/2026-09-26_吸纳/a.md", "/x"))
+
+    def test_relative_root(self):
+        # 默认根 "." —— rg 输出相对路径时的常见形态
+        self.assertTrue(s._is_noise_path("repos/lib.py", "."))
+        self.assertFalse(s._is_noise_path("src/app.py", "."))
+
+    def test_out_of_root_falls_back_to_full_path(self):
+        # 不在根之下（软链/越界）：退回整条路径判定
+        self.assertTrue(s._is_noise_path("/other/repos/lib.py", "/x"))
+        self.assertFalse(s._is_noise_path("/other/src/lib.py", "/x"))
+
+    def test_noise_floor_clean_first(self):
+        rows = [("/x/repos/a.py", 0, ""), ("/x/src/b.py", 0, "")]
+        out = s._apply_noise_floor(rows, "/x", 30)
+        self.assertEqual(out[0][0], "/x/src/b.py",
+                         "真源必须排在噪声档之前")
+
+    def test_noise_floor_backfills_when_clean_short(self):
+        # 真源不足时噪声档补满（不是排除，保证仍可达）
+        rows = [("/x/repos/a.py", 0, ""), ("/x/src/b.py", 0, "")]
+        out = s._apply_noise_floor(rows, "/x", 2)
+        self.assertEqual(len(out), 2)
+
+
+class TestNoisePathNoSyscall(unittest.TestCase):
+    """性能守门：判定路径不得再触发任何文件系统解析调用。"""
+
+    def test_does_not_call_path_resolve(self):
+        with mock.patch.object(Path, "resolve",
+                               side_effect=AssertionError("又调 Path.resolve() 了")):
+            rows = [(f"/root/repos/f{i}.py", 0, "") for i in range(100)]
+            s._apply_noise_floor(rows, "/root", 30)
+
+    def test_does_not_call_realpath_or_lstat(self):
+        with mock.patch.object(os.path, "realpath",
+                               side_effect=AssertionError("又调 realpath() 了")), \
+             mock.patch.object(os, "lstat",
+                               side_effect=AssertionError("又调 lstat() 了")):
+            rows = [(f"/root/repos/f{i}.py", 0, "") for i in range(100)]
+            s._apply_noise_floor(rows, "/root", 30)
+
+
+class TestReadLinesSinglePass(unittest.TestCase):
+    """read_lines 单遍读取：区间/夹取/越界/空文件行为与原实现一致。"""
+
+    def _write(self, tmp, text):
+        f = Path(tmp) / "a.txt"
+        f.write_text(text, encoding="utf-8")
+        return str(f)
+
+    def test_range_slice(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            fp = self._write(tmp, "\n".join(f"L{i}" for i in range(1, 11)) + "\n")
+            text, rc = s.read_lines(fp, "3-5")
+            self.assertEqual(rc, 0)
+            self.assertIn("3: L3", text)
+            self.assertIn("5: L5", text)
+            self.assertNotIn("6: L6", text)
+            self.assertIn("共 10 行", text)
+
+    def test_clamped_to_total(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            fp = self._write(tmp, "L1\nL2\n")
+            text, rc = s.read_lines(fp, "1-99")
+            self.assertEqual(rc, 0)
+            self.assertIn("第 1-2 行", text)
+
+    def test_start_past_end(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            fp = self._write(tmp, "L1\n")
+            text, rc = s.read_lines(fp, "5-6")
+            self.assertEqual(rc, 1)
+            self.assertIn("只有 1 行", text)
+
+    def test_empty_file(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            fp = self._write(tmp, "")
+            text, rc = s.read_lines(fp, "1-2")
+            self.assertEqual(rc, 1)
+            self.assertIn("只有 0 行", text)
+
+    def test_bad_spec(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            fp = self._write(tmp, "L1\n")
+            text, rc = s.read_lines(fp, "abc")
+            self.assertEqual(rc, 1)
+            self.assertIn("N-M", text)
+
+
+if __name__ == "__main__":
+    unittest.main()

package/sub-skills/local-seek/tests/test_seek_degradation.py

@@ -0,0 +1,111 @@
+#!/usr/bin/env python3
+"""local-seek 降级链与 --count 排序回归测试（P0-2 / P0-4，2026-09-13）。
+
+守的两个缺陷：
+  1. 降级链曾把「工具缺失」伪装成「搜索结论」：scope=code 且缺 rg 时落
+     mdfind（Spotlight 不索引源码内容）→ 搜 argo 自身符号返回 24 条外部
+     陈旧副本、漏掉正主，还报「未找到匹配（mdfind）」。修复后：缺 rg 直落
+     grep，两者皆无才显式报错。
+  2. --count 曾按 rg 原始输出顺序（目录遍历序）截断，「哪些文件命中最多」
+     系统性答错。修复后：全量收集→按命中数降序→取前 N。
+
+运行：
+  cd ~/.agents/skills/argo
+  python3 -m pytest sub-skills/local-seek/tests/test_seek_degradation.py -q
+"""
+
+from __future__ import annotations
+
+import io
+import json
+import sys
+import tempfile
+import unittest
+from contextlib import redirect_stdout
+from pathlib import Path
+from unittest import mock
+
+SCRIPTS = Path(__file__).resolve().parent.parent / "scripts"
+sys.path.insert(0, str(SCRIPTS))
+
+import seek as s  # noqa: E402
+
+
+def _run_main(argv):
+    """跑 seek.main()，捕获 stdout，返回 (exit_code, stdout)。"""
+    with mock.patch.object(sys, "argv", ["seek.py"] + argv):
+        buf = io.StringIO()
+        try:
+            with redirect_stdout(buf):
+                code = s.main()
+        except SystemExit as e:
+            code = e.code or 0
+    return code or 0, buf.getvalue()
+
+
+class TestDegradationChain(unittest.TestCase):
+    """scope=code 缺 rg 时的降级（全部 mock，不依赖本机装了什么）。"""
+
+    def _argv(self, tmp: str) -> list[str]:
+        return ["def needle", "--scope", "code", "--path", tmp, "--json"]
+
+    def test_rg_missing_falls_to_grep(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            (Path(tmp) / "a.py").write_text("def needle(x):\n    return x\n")
+            with mock.patch.object(s, "tool_exists",
+                                   lambda name: name in ("grep", "mdfind")), \
+                 mock.patch.object(s, "resolve_grep", lambda: "/usr/bin/grep"), \
+                 mock.patch.object(s, "grep_search",
+                                   lambda *a, **k: ([(str(Path(tmp) / "a.py"), 1, "def needle(x)")], None)):
+                code, out = _run_main(self._argv(tmp))
+        self.assertEqual(code, 0)
+        data = json.loads(out)
+        self.assertEqual(data["engine"], "grep",
+                         "缺 rg 时必须落 grep，不能落 mdfind")
+
+    def test_rg_and_grep_missing_reports_tools_not_nomatch(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            with mock.patch.object(s, "tool_exists", lambda name: False), \
+                 mock.patch.object(s, "resolve_grep", lambda: None):
+                code, out = _run_main(self._argv(tmp))
+        self.assertEqual(code, 1)
+        self.assertIn("rg", out)
+        self.assertIn("grep", out)
+        self.assertNotIn("未找到匹配", out,
+                         "工具缺失不得伪装成搜索结论")
+
+    def test_real_rg_still_used(self):
+        """rg 在位时行为不变（防把好路径改坏）。"""
+        with tempfile.TemporaryDirectory() as tmp:
+            (Path(tmp) / "a.py").write_text("def needle(x):\n    return x\n")
+            code, out = _run_main(self._argv(tmp))
+            self.assertEqual(code, 0)
+            self.assertEqual(json.loads(out)["engine"], "rg")
+
+
+class TestCountOrdering(unittest.TestCase):
+    """--count 按命中数降序（真实 rg 端到端）。"""
+
+    def test_most_hits_first(self):
+        if not s.tool_exists("rg"):
+            self.skipTest("本机无 rg")
+        with tempfile.TemporaryDirectory() as tmp:
+            # 遍历序（字典序）在前面的文件命中少、后面的命中多：
+            # 旧实现按遍历序截断会答错。
+            (Path(tmp) / "aaa.txt").write_text("needle\n")          # 1 次
+            (Path(tmp) / "zzz.txt").write_text("needle\nneedle\nneedle\n")  # 3 次
+            code, out = _run_main(
+                ["needle", "--scope", "code", "--path", tmp, "--count",
+                 "--json"])
+            self.assertEqual(code, 0)
+            data = json.loads(out)
+            results = data.get("results") or []
+            files = [r.get("path") if isinstance(r, dict) else r[0]
+                     for r in results]
+            self.assertTrue(files, "无结果")
+            self.assertIn("zzz.txt", files[0],
+                          f"命中最多的文件必须排第一，实际 {files}")
+
+
+if __name__ == "__main__":
+    unittest.main()