✨ feat(tsl-codegen): add decoupled documentation toolkit

Generate TSL API Markdown from YAML or JSON into a configurable project scope.\nAdd file and directory lint modes, tags-aware indexing, and keyword search across tags and descriptions.\nBundle the toolkit through the playbook build and sync workflows.
2026-07-20 09:08:38 +08:00
parent 1d5304e7b6
commit c69278283f
18 changed files with 13955 additions and 12821 deletions
@@ -0,0 +1,85 @@
+import json
+import subprocess
+import sys
+import tempfile
+import unittest
+from pathlib import Path
+
+
+SCRIPT = Path(__file__).parents[1] / "scripts" / "generate.py"
+
+
+class DocGenCliTest(unittest.TestCase):
+    def setUp(self):
+        self.temp_dir = tempfile.TemporaryDirectory()
+        self.root = Path(self.temp_dir.name)
+        self.input = self.root / "entry.json"
+        self.input.write_text(
+            json.dumps(
+                {
+                    "module": "项目 / 示例",
+                    "path": "base/my_functions",
+                    "functions": [
+                        {
+                            "signature": "demo()",
+                            "desc": "示例函数。",
+                            "returns": "nil",
+                        }
+                    ],
+                },
+                ensure_ascii=False,
+            ),
+            encoding="utf-8",
+        )
+
+    def tearDown(self):
+        self.temp_dir.cleanup()
+
+    def run_cli(self, *args):
+        return subprocess.run(
+            [sys.executable, str(SCRIPT), str(self.input), *args],
+            capture_output=True,
+            text=True,
+            encoding="utf-8",
+            cwd=self.root,
+        )
+
+    def test_default_scope_writes_configured_path_under_project(self):
+        result = self.run_cli()
+        output = (
+            self.root
+            / "skills"
+            / "tsl-api-reference"
+            / "references"
+            / "codegen"
+            / "project"
+            / "base"
+            / "my_functions.md"
+        )
+        self.assertEqual(result.returncode, 0, result.stderr)
+        self.assertTrue(output.is_file())
+        self.assertTrue(output.read_text(encoding="utf-8").startswith("# 项目 / 示例\n"))
+
+    def test_custom_scope_changes_first_destination_directory(self):
+        result = self.run_cli("--scope", "my-project")
+        output = (
+            self.root
+            / "skills"
+            / "tsl-api-reference"
+            / "references"
+            / "codegen"
+            / "my-project"
+            / "base"
+            / "my_functions.md"
+        )
+        self.assertEqual(result.returncode, 0, result.stderr)
+        self.assertTrue(output.is_file())
+
+    def test_output_option_is_rejected(self):
+        result = self.run_cli("--output", str(self.root / "out.md"))
+        self.assertNotEqual(result.returncode, 0)
+        self.assertIn("unrecognized arguments: --output", result.stderr)
+
+
+if __name__ == "__main__":
+    unittest.main()