🐛 fix(tsl-syntax): index precise sections and enforce map integrity

test/test_tsl_syntax_lookup.py

@@ -66,12 +66,67 @@ class TslSyntaxLookupTests(unittest.TestCase):
         self.assertNotIn(section.body.rstrip(), query_completed.stdout)
         self.assertIn(section.body.rstrip(), section_completed.stdout)
 
-    def test_parser_creates_unique_h2_h3_section_ids(self):
+    def test_parser_creates_unique_h2_h3_h4_section_ids(self):
         sections = lookup.load_sections(lookup.DEFAULT_REFERENCES_DIR)
         ids = [section.id for section in sections]
         self.assertEqual(len(ids), len(set(ids)))
         self.assertTrue(any("05_functions_and_calls" in value for value in ids))
 
+    def test_parser_indexes_h4_pitfall_sections(self):
+        sections = lookup.load_sections(lookup.DEFAULT_REFERENCES_DIR)
+
+        self.assertTrue(any(len(section.heading_path) == 3 for section in sections))
+        self.assertTrue(any("把-当成赋值" in section.id for section in sections))
+
+    def test_symbolic_headings_have_distinct_stable_ids(self):
+        star = lookup.section_id("sample.md", ("Examples", "with *"))
+        double_star = lookup.section_id("sample.md", ("Examples", "with **"))
+
+        self.assertNotEqual(star, double_star)
+        self.assertNotRegex(double_star, r"-2$")
+
+    def test_check_requires_one_nonempty_duty_section_per_page(self):
+        with tempfile.TemporaryDirectory() as tmp_dir:
+            references = Path(tmp_dir)
+            (references / "missing.md").write_text(
+                "# Missing\n\n## Rules\n\nText.\n",
+                encoding="utf-8",
+                newline="\n",
+            )
+            (references / "duplicate.md").write_text(
+                "# Duplicate\n\n"
+                "## 本篇职责\n\n"
+                "One.\n\n"
+                "## 本篇职责\n\n"
+                "Two.\n",
+                encoding="utf-8",
+                newline="\n",
+            )
+
+            problems = lookup.validate_references(references)
+
+        messages = "\n".join(problem.message for problem in problems)
+        self.assertIn("必须有且仅有一个非空「本篇职责」", messages)
+
+    def test_check_rejects_h2_h3_h4_heading_level_jumps(self):
+        with tempfile.TemporaryDirectory() as tmp_dir:
+            references = Path(tmp_dir)
+            (references / "sample.md").write_text(
+                "# Sample\n\n"
+                "## 本篇职责\n\n"
+                "Summary.\n\n"
+                "#### Skipped H3\n\n"
+                "Details.\n",
+                encoding="utf-8",
+                newline="\n",
+            )
+
+            problems = lookup.validate_references(references)
+
+        self.assertTrue(
+            any("标题层级跳跃" in problem.message for problem in problems), problems
+        )
+
     def test_write_mode_includes_file_model_and_direct_example(self):
         result = lookup.query_sections("写函数 命名参数", "write", limit=4)
         rendered = lookup.render_candidates(result)
@@ -200,6 +255,8 @@ class TslSyntaxLookupTests(unittest.TestCase):
             page = references / "sample.md"
             page.write_text(
                 "# Sample\n\n"
+                "## 本篇职责\n\n"
+                "Structured metadata sample.\n\n"
                 "## Example\n\n"
                 "代码块身份：配置片段 / 概念骨架\n"
                 "代码块说明：This is structured metadata.\n\n"
@@ -213,7 +270,10 @@ class TslSyntaxLookupTests(unittest.TestCase):
             sections = lookup.load_sections(references)
             problems = lookup.validate_references(references)
 
-        self.assertEqual(sections[0].identities, ("配置片段 / 概念骨架",))
+        example = next(
+            section for section in sections if section.heading_path == ("Example",)
+        )
+        self.assertEqual(example.identities, ("配置片段 / 概念骨架",))
         self.assertEqual(problems, [])
 
     def test_check_accumulates_fence_identity_and_link_problems(self):
@@ -243,6 +303,8 @@ class TslSyntaxLookupTests(unittest.TestCase):
             references = Path(tmp_dir)
             (references / "sample.md").write_text(
                 "# Sample\n\n"
+                "## 本篇职责\n\n"
+                "Inline-code link sample.\n\n"
                 "## Operators\n\n"
                 "Use `function operator[](index);`.\n",
                 encoding="utf-8",