csh/playbook
1
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

📝 docs(tsl): rebuild canonical syntax and routing manual

Browse Source
This commit is contained in:
csh
2026-04-22 16:59:20 +08:00
parent 3ed5052e61
commit 96b705b00b
83 changed files with 46446 additions and 323 deletions
Download Patch File Download Diff File Expand all files Collapse all files
tests/cli/test_playbook_cli.py
+196 -8
View File
@@ -6,17 +6,41 @@ from pathlib import Path
ROOT = Path(__file__).resolve().parents[2]
SCRIPT = ROOT / "scripts" / "playbook.py"
CUSTOM_DEPLOY_ROOT = "custom/playbook"
def run_cli(*args):
def run_script(script, *args):
return subprocess.run(
[sys.executable, str(SCRIPT), *args],
[sys.executable, str(script), *args],
capture_output=True,
text=True,
)
def run_cli(*args):
return run_script(SCRIPT, *args)
def write_config(root: Path, name: str, body: str) -> Path:
config_path = root / name
config_path.write_text(body, encoding="utf-8")
return config_path
class PlaybookCliTests(unittest.TestCase):
def assert_style_cleanup_tsl_docs_prefix(
self, root: Path, agents_home: Path, docs_prefix: str
) -> None:
agents_index = (root / ".agents" / "tsl" / "index.md").read_text(encoding="utf-8")
self.assertIn(f"`{docs_prefix}/tsl/index.md`", agents_index)
self.assertNotIn("`docs/tsl/index.md`", agents_index)
skill_file = (agents_home / "skills" / "style-cleanup" / "SKILL.md").read_text(
encoding="utf-8"
)
self.assertIn(f"`{docs_prefix}/tsl/code_style.md`", skill_file)
self.assertNotIn("`docs/tsl/code_style.md`", skill_file)
def test_help_shows_usage(self):
result = run_cli("-h")
self.assertEqual(result.returncode, 0)
@@ -28,9 +52,10 @@ class PlaybookCliTests(unittest.TestCase):
self.assertIn("-config", result.stdout + result.stderr)
def test_action_order(self):
config_body = """
config_body = f"""
[playbook]
project_root = "."
deploy_root = "{CUSTOM_DEPLOY_ROOT}"
[format_md]
@@ -47,8 +72,68 @@ langs = ["tsl"]
self.assertIn("sync_standards", output)
self.assertIn("format_md", output)
def test_format_md_only_does_not_require_deploy_root(self):
with tempfile.TemporaryDirectory() as tmp_dir:
config_body = f"""
[playbook]
project_root = "{tmp_dir}"
[format_md]
"""
config_path = Path(tmp_dir) / "playbook.toml"
config_path.write_text(config_body, encoding="utf-8")
result = run_cli("-config", str(config_path))
self.assertEqual(result.returncode, 0)
def test_vendor_creates_snapshot(self):
with tempfile.TemporaryDirectory() as tmp_dir:
root = Path(tmp_dir)
config_body = f"""
[playbook]
project_root = "{tmp_dir}"
deploy_root = "{CUSTOM_DEPLOY_ROOT}"
[vendor]
langs = ["tsl"]
"""
config_path = write_config(root, "playbook.toml", config_body)
result = run_cli("-config", str(config_path))
snapshot = root / CUSTOM_DEPLOY_ROOT / "SOURCE.md"
self.assertEqual(result.returncode, 0)
self.assertTrue(snapshot.is_file())
def test_vendor_docs_index_uses_new_tsl_entrypoints(self):
with tempfile.TemporaryDirectory() as tmp_dir:
root = Path(tmp_dir)
config_body = f"""
[playbook]
project_root = "{tmp_dir}"
deploy_root = "{CUSTOM_DEPLOY_ROOT}"
[vendor]
langs = ["tsl"]
"""
config_path = write_config(root, "playbook.toml", config_body)
result = run_cli("-config", str(config_path))
docs_index = root / CUSTOM_DEPLOY_ROOT / "docs/index.md"
self.assertEqual(result.returncode, 0)
text = docs_index.read_text(encoding="utf-8")
self.assertIn("`tsl/index.md`", text)
self.assertIn("`tsl/syntax/index.md`", text)
self.assertIn("`tsl/finance/index.md`", text)
self.assertIn("`tsl/modules/index.md`", text)
self.assertIn("`tsl/reference/index.md`", text)
self.assertNotIn("`tsl/syntax_book/index.md`", text)
def test_external_clone_requires_explicit_deploy_root(self):
with tempfile.TemporaryDirectory() as tmp_dir:
root = Path(tmp_dir)
config_body = f"""
[playbook]
project_root = "{tmp_dir}"
@@ -56,20 +141,19 @@ project_root = "{tmp_dir}"
[vendor]
langs = ["tsl"]
"""
config_path = Path(tmp_dir) / "playbook.toml"
config_path.write_text(config_body, encoding="utf-8")
config_path = write_config(root, "playbook.toml", config_body)
result = run_cli("-config", str(config_path))
snapshot = Path(tmp_dir) / "docs/standards/playbook/SOURCE.md"
self.assertEqual(result.returncode, 0)
self.assertTrue(snapshot.is_file())
self.assertNotEqual(result.returncode, 0)
self.assertIn("deploy_root", result.stdout + result.stderr)
def test_sync_memory_bank_creates_memory_bank(self):
with tempfile.TemporaryDirectory() as tmp_dir:
config_body = f"""
[playbook]
project_root = "{tmp_dir}"
deploy_root = "{CUSTOM_DEPLOY_ROOT}"
[sync_memory_bank]
project_name = "Demo"
@@ -88,6 +172,7 @@ project_name = "Demo"
config_body = f"""
[playbook]
project_root = "{tmp_dir}"
deploy_root = "{CUSTOM_DEPLOY_ROOT}"
[sync_standards]
langs = ["tsl"]
@@ -110,6 +195,7 @@ langs = ["tsl"]
f"""
[playbook]
project_root = "{tmp_dir}"
deploy_root = "{CUSTOM_DEPLOY_ROOT}"
[sync_standards]
langs = ["tsl"]
@@ -126,6 +212,7 @@ no_backup = true
f"""
[playbook]
project_root = "{tmp_dir}"
deploy_root = "{CUSTOM_DEPLOY_ROOT}"
[sync_standards]
langs = ["tsl", "cpp"]
@@ -146,6 +233,7 @@ no_backup = true
config_body = f"""
[playbook]
project_root = "{tmp_dir}"
deploy_root = "{CUSTOM_DEPLOY_ROOT}"
[sync_standards]
langs = ["tsl"]
@@ -171,6 +259,7 @@ langs = ["tsl"]
config_body = f"""
[playbook]
project_root = "{tmp_dir}"
deploy_root = "{CUSTOM_DEPLOY_ROOT}"
[install_skills]
agents_home = "{target}"
@@ -186,12 +275,34 @@ skills = ["brainstorming"]
self.assertEqual(result.returncode, 0)
self.assertTrue(skill_file.is_file())
def test_install_skills_rejects_removed_tsl_guide(self):
with tempfile.TemporaryDirectory() as tmp_dir:
target = Path(tmp_dir) / "agents"
config_body = f"""
[playbook]
project_root = "{tmp_dir}"
deploy_root = "{CUSTOM_DEPLOY_ROOT}"
[install_skills]
agents_home = "{target}"
mode = "list"
skills = ["tsl-guide"]
"""
config_path = Path(tmp_dir) / "playbook.toml"
config_path.write_text(config_body, encoding="utf-8")
result = run_cli("-config", str(config_path))
self.assertNotEqual(result.returncode, 0)
self.assertIn("skill not found: tsl-guide", result.stdout + result.stderr)
def test_install_skills_rejects_codex_home(self):
with tempfile.TemporaryDirectory() as tmp_dir:
target = Path(tmp_dir) / "codex"
config_body = f"""
[playbook]
project_root = "{tmp_dir}"
deploy_root = "{CUSTOM_DEPLOY_ROOT}"
[install_skills]
codex_home = "{target}"
@@ -206,5 +317,82 @@ skills = ["brainstorming"]
self.assertNotEqual(result.returncode, 0)
self.assertIn("codex_home", result.stdout + result.stderr)
def test_external_clone_flow_rewrites_links_with_configured_deploy_root(self):
with tempfile.TemporaryDirectory() as tmp_dir:
root = Path(tmp_dir)
agents_home = root / "agents-home"
config_body = f"""
[playbook]
project_root = "{tmp_dir}"
deploy_root = "{CUSTOM_DEPLOY_ROOT}"
[vendor]
langs = ["tsl"]
[sync_standards]
langs = ["tsl"]
no_backup = true
[install_skills]
agents_home = "{agents_home}"
mode = "list"
skills = ["style-cleanup"]
"""
config_path = write_config(root, "playbook.toml", config_body)
result = run_cli("-config", str(config_path))
self.assertEqual(result.returncode, 0, msg=result.stdout + result.stderr)
self.assertTrue((root / CUSTOM_DEPLOY_ROOT / "SOURCE.md").is_file())
self.assert_style_cleanup_tsl_docs_prefix(
root, agents_home, f"{CUSTOM_DEPLOY_ROOT}/docs"
)
def test_deployed_snapshot_rewrites_links_from_snapshot_location(self):
with tempfile.TemporaryDirectory() as tmp_dir:
root = Path(tmp_dir)
vendor_config = write_config(
root,
"vendor.toml",
f"""
[playbook]
project_root = "{tmp_dir}"
deploy_root = "{CUSTOM_DEPLOY_ROOT}"
[vendor]
langs = ["tsl"]
""",
)
vendor_result = run_cli("-config", str(vendor_config))
self.assertEqual(vendor_result.returncode, 0, msg=vendor_result.stdout + vendor_result.stderr)
vendored_script = root / CUSTOM_DEPLOY_ROOT / "scripts" / "playbook.py"
agents_home = root / "local-agents"
sync_config = write_config(
root,
"sync.toml",
f"""
[playbook]
project_root = "{tmp_dir}"
deploy_root = "{CUSTOM_DEPLOY_ROOT}"
[sync_standards]
langs = ["tsl"]
no_backup = true
[install_skills]
agents_home = "{agents_home}"
mode = "list"
skills = ["style-cleanup"]
""",
)
sync_result = run_script(vendored_script, "-config", str(sync_config))
self.assertEqual(sync_result.returncode, 0, msg=sync_result.stdout + sync_result.stderr)
self.assert_style_cleanup_tsl_docs_prefix(
root, agents_home, f"{CUSTOM_DEPLOY_ROOT}/docs"
)
if __name__ == "__main__":
unittest.main()
tests/test_playbook_docs_index.py
+61
View File
@@ -0,0 +1,61 @@
import importlib.util
import tempfile
import unittest
from pathlib import Path
ROOT = Path(__file__).resolve().parents[1]
SCRIPT = ROOT / "scripts" / "playbook.py"
def load_playbook_module():
spec = importlib.util.spec_from_file_location("playbook_script", SCRIPT)
module = importlib.util.module_from_spec(spec)
assert spec.loader is not None
spec.loader.exec_module(module)
return module
class PlaybookDocsIndexTests(unittest.TestCase):
def test_build_docs_index_lines_uses_canonical_sections(self):
playbook = load_playbook_module()
with tempfile.TemporaryDirectory() as tmp_dir:
source = Path(tmp_dir) / "index.md"
source.write_text(
"\n".join(
[
"# 文档导航（Docs Index）",
"",
"仓库级说明。",
"",
"## 跨语言（common）",
"",
"- 公共入口：`common/commit_message.md`",
"",
"## TSL（tsl/tsf）",
"",
"- 自定义 TSL 入口：`tsl/custom.md`",
"",
"## Python（python）",
"",
"- Python 入口：`python/style_guide.md`",
"",
]
)
+ "\n",
encoding="utf-8",
)
lines = playbook.build_docs_index_lines(["tsl"], source)
self.assertEqual(lines[0], "# 文档导航（Docs Index）")
self.assertEqual(lines[2], "本快照为裁剪版 Playbook（langs: tsl）。")
self.assertIn("## 跨语言（common）", lines)
self.assertIn("- 公共入口：`common/commit_message.md`", lines)
self.assertIn("## TSL（tsl/tsf）", lines)
self.assertIn("- 自定义 TSL 入口：`tsl/custom.md`", lines)
self.assertNotIn("## Python（python）", lines)
if __name__ == "__main__":
unittest.main()
tests/test_tsl_entrypoints_consistency.py
+56
View File
@@ -0,0 +1,56 @@
import unittest
from pathlib import Path
ROOT = Path(__file__).resolve().parents[1]
RULESET_TSL = ROOT / "rulesets" / "tsl" / "index.md"
README = ROOT / "README.md"
PLAYBOOK_EXAMPLE = ROOT / "playbook.toml.example"
SKILLS_DOC = ROOT / "SKILLS.md"
TEMPLATES_CI_README = ROOT / "templates" / "ci" / "README.md"
REMOVED_TSL_GUIDE = ROOT / "codex" / "skills" / "tsl-guide"
class TslEntrypointsConsistencyTests(unittest.TestCase):
def test_ruleset_lists_canonical_tsl_layers(self):
text = RULESET_TSL.read_text(encoding="utf-8")
self.assertIn("docs/tsl/index.md", text)
self.assertIn("docs/tsl/syntax/index.md", text)
self.assertIn("docs/tsl/finance/index.md", text)
self.assertIn("docs/tsl/modules/index.md", text)
self.assertIn("docs/tsl/reference/index.md", text)
def test_readme_only_lists_two_official_deployment_routes(self):
text = README.read_text(encoding="utf-8")
self.assertIn("方式一：git subtree", text)
self.assertIn("方式二：外部 clone 后执行部署", text)
self.assertIn("`project_root`：目标项目根目录", text)
self.assertIn("`deploy_root`：相对于 `project_root` 的项目内目标目录", text)
self.assertIn("不是外部 clone 出来的 Playbook 仓库路径", text)
self.assertIn("外部 clone 场景下必须显式填写 `deploy_root`", text)
self.assertNotIn("方式二：手动复制快照", text)
self.assertNotIn("方式三：CLI 裁剪复制", text)
self.assertNotIn("如果省略 `deploy_root`，默认仍部署到 `docs/standards/playbook`", text)
def test_playbook_example_defines_deploy_root_as_target_path(self):
text = PLAYBOOK_EXAMPLE.read_text(encoding="utf-8")
self.assertIn('deploy_root = "docs/standards/playbook"', text)
self.assertIn("相对于 project_root", text)
self.assertIn("不是外部 clone 的 playbook 路径", text)
self.assertIn("从外部 clone 执行时必填", text)
self.assertNotIn("target_dir", text)
def test_deployment_docs_do_not_reference_legacy_terms(self):
self.assertNotIn("vendoring", README.read_text(encoding="utf-8"))
self.assertNotIn("`.tmp`", README.read_text(encoding="utf-8"))
self.assertNotIn("vendoring", SKILLS_DOC.read_text(encoding="utf-8"))
self.assertNotIn("vendoring", TEMPLATES_CI_README.read_text(encoding="utf-8"))
def test_repo_no_longer_ships_tsl_guide_skill(self):
self.assertFalse(REMOVED_TSL_GUIDE.exists())
self.assertNotIn("tsl-guide", README.read_text(encoding="utf-8"))
self.assertNotIn("tsl-guide", SKILLS_DOC.read_text(encoding="utf-8"))
self.assertNotIn("$tsl-guide", RULESET_TSL.read_text(encoding="utf-8"))
if __name__ == "__main__":
unittest.main()