diff --git a/README.md b/README.md index 4763df2..d52810f 100644 --- a/README.md +++ b/README.md @@ -39,6 +39,7 @@ Playbook：TSL（`.tsl`/`.tsf`）+ C++ + Python 工程规范与代理规则合 - `docs/python/configuration.md`：Python 配置清单（落地时从 `templates/python/` 复制到项目根目录）。 - `templates/cpp/`：C++ 落地模板（`.clang-format`、`conanfile.txt`、`CMakeUserPresets.json`、`CMakeLists.txt`）。 - `templates/python/`：Python 落地模板（`pyproject.toml` 工具配置、`.flake8`、`.pylintrc`、`.pre-commit-config.yaml`、`.editorconfig`、`.vscode/settings.json`）。 +- `templates/ci/`：目标项目 CI 示例模板（如 Gitea Actions），用于自动化校验部分规范。 ## .agents/（代理规则） @@ -246,7 +247,7 @@ sh docs/standards/playbook/scripts/sync_standards.sh tsl cpp 脚本会： -- 生成裁剪快照到 `docs/standards/playbook/`（包含 `docs/common/` + 选定语言目录 + 对应 `.agents//` + `scripts/` + `.gitattributes` + 相关 `templates//`） +- 生成裁剪快照到 `docs/standards/playbook/`（包含 `docs/common/` + 选定语言目录 + 对应 `.agents//` + `scripts/` + `.gitattributes` + 通用 `templates/ci/` + 相关 `templates//`） - 自动执行 `docs/standards/playbook/scripts/sync_standards.*`，把 `.agents//` 与 `.gitattributes` 落地到目标项目根目录 - 生成 `docs/standards/playbook/SOURCE.md` 记录来源与版本信息 diff --git a/scripts/vendor_playbook.bat b/scripts/vendor_playbook.bat index 2f2f9e3..8cbf850 100644 --- a/scripts/vendor_playbook.bat +++ b/scripts/vendor_playbook.bat @@ -80,6 +80,14 @@ copy /y "%SRC%\\.agents\\index.md" "%DEST_PREFIX%\\.agents\\index.md" >nul if not exist "%DEST_PREFIX%\\templates" mkdir "%DEST_PREFIX%\\templates" +if exist "%SRC%\\templates\\ci" ( + xcopy "%SRC%\\templates\\ci\\*" "%DEST_PREFIX%\\templates\\ci\\" /e /i /y >nul + if errorlevel 1 ( + echo ERROR: failed to copy templates\\ci + exit /b 1 + ) +) + set "LANGS_CSV=" for %%L in (%LANGS%) do ( echo %%~L| findstr /r "[\\/]" >nul && ( diff --git a/scripts/vendor_playbook.ps1 b/scripts/vendor_playbook.ps1 index cb119c8..c1631ba 100644 --- a/scripts/vendor_playbook.ps1 +++ b/scripts/vendor_playbook.ps1 @@ -81,6 +81,11 @@ Copy-Item (Join-Path $Src ".agents/index.md") (Join-Path $AgentsDir "index.md") $TemplatesDir = Join-Path $DestPrefix "templates" New-Item -ItemType Directory -Path $TemplatesDir -Force | Out-Null +$ciTplSrc = Join-Path (Join-Path $Src "templates") "ci" +if (Test-Path $ciTplSrc) { + Copy-Item $ciTplSrc $TemplatesDir -Recurse -Force +} + foreach ($lang in $Langs) { $docsSrc = Join-Path (Join-Path $Src "docs") $lang if (-not (Test-Path $docsSrc)) { throw "Docs not found for lang=$lang ($docsSrc)" } diff --git a/scripts/vendor_playbook.sh b/scripts/vendor_playbook.sh index 2aa29c2..6478650 100644 --- a/scripts/vendor_playbook.sh +++ b/scripts/vendor_playbook.sh @@ -81,6 +81,9 @@ mkdir -p "$DEST_PREFIX/.agents" cp "$SRC/.agents/index.md" "$DEST_PREFIX/.agents/index.md" mkdir -p "$DEST_PREFIX/templates" +if [ -d "$SRC/templates/ci" ]; then + cp -R "$SRC/templates/ci" "$DEST_PREFIX/templates/" +fi old_ifs="${IFS}" IFS=', ' diff --git a/templates/ci/README.md b/templates/ci/README.md new file mode 100644 index 0000000..1c5f824 --- /dev/null +++ b/templates/ci/README.md @@ -0,0 +1,34 @@ +# CI 模板（templates/ci） + +本目录提供“目标项目可复制启用”的 CI 模板示例，用于在 CI 中自动化校验部分 Playbook 规范。 + +当前提供： + +- `gitea/`：Gitea Actions（GitHub Actions 语法） + +## 使用（Gitea Actions） + +前提：目标项目已经 vendoring Playbook（例如 `docs/standards/playbook/`）。 + +复制到目标项目根目录： + +```sh +cp -R docs/standards/playbook/templates/ci/gitea/.gitea ./ +``` + +提交： + +```sh +git add .gitea +git commit -m ":memo: docs(ci): add standards check workflow" +``` + +## commit message 校验 + +工作流会运行 `.gitea/ci/commit_message_lint.py`： + +- 规范来源（自动探测其一）： + - `docs/common/commit_message.md` + - `docs/standards/playbook/docs/common/commit_message.md` +- 默认要求 emoji；如需允许无 emoji：在 workflow 中设置 `COMMIT_LINT_REQUIRE_EMOJI=0`。 + diff --git a/templates/ci/gitea/.gitea/ci/commit_message_lint.py b/templates/ci/gitea/.gitea/ci/commit_message_lint.py new file mode 100644 index 0000000..554461f --- /dev/null +++ b/templates/ci/gitea/.gitea/ci/commit_message_lint.py @@ -0,0 +1,210 @@ +#!/usr/bin/env python3 +from __future__ import annotations + +import json +import os +import pathlib +import re +import subprocess +import sys +from typing import Dict, List, Optional, Tuple + + +def _eprint(*args: object) -> None: + print(*args, file=sys.stderr) + + +def _git(*args: str) -> str: + return subprocess.check_output(["git", *args], text=True).strip() + + +def _repo_root() -> pathlib.Path: + return pathlib.Path(_git("rev-parse", "--show-toplevel")) + + +def _find_commit_spec(root: pathlib.Path) -> pathlib.Path: + candidates = [ + root / "docs" / "common" / "commit_message.md", + root / "docs" / "standards" / "playbook" / "docs" / "common" / "commit_message.md", + ] + for path in candidates: + if path.is_file(): + return path + raise FileNotFoundError( + "commit_message.md not found; expected one of:\n" + + "\n".join(f"- {p}" for p in candidates) + ) + + +def _parse_type_emoji_mapping(md_text: str) -> Dict[str, str]: + mapping: Dict[str, str] = {} + for raw_line in md_text.splitlines(): + line = raw_line.strip() + if not (line.startswith("|") and line.endswith("|")): + continue + if "type" in line and "emoji" in line: + continue + if re.fullmatch(r"\|\s*-+\s*(\|\s*-+\s*)+\|", line): + continue + + cols = [c.strip() for c in line.strip("|").split("|")] + if len(cols) < 2: + continue + + m_type = re.search(r"`([^`]+)`", cols[0]) + m_emoji = re.search(r"`(:[^`]+:)`", cols[1]) + if not m_type or not m_emoji: + continue + + type_name = m_type.group(1).strip() + emoji_code = m_emoji.group(1).strip() + mapping[type_name] = emoji_code + + if not mapping: + raise ValueError("failed to parse type/emoji mapping from commit_message.md") + return mapping + + +def _validate_subject_line( + line: str, + mapping: Dict[str, str], + *, + require_emoji: bool, +) -> Optional[str]: + subject = line.strip() + if not subject: + return "empty subject" + + m = re.match( + r"^(?:(?P:[a-z0-9_+-]+:)\s+)?" + r"(?P[a-z]+)" + r"(?P\([a-z0-9_]+\))?" + r":\s+(?P.+)$", + subject, + ) + if not m: + return "does not match ':emoji: type(scope): subject' or 'type(scope): subject'" + + emoji = m.group("emoji") + type_name = m.group("type") + text = (m.group("text") or "").rstrip() + + if type_name not in mapping: + return f"unknown type: {type_name}" + + if emoji: + expected = mapping[type_name] + if emoji != expected: + return f"emoji/type mismatch: got {emoji} {type_name}, expected {expected} for type {type_name}" + elif require_emoji: + return "missing emoji (set COMMIT_LINT_REQUIRE_EMOJI=0 to allow)" + + if text.endswith((".", "。")): + return "subject should not end with a period" + + return None + + +def _load_event_payload() -> Tuple[str, Optional[dict]]: + event_name = os.getenv("GITHUB_EVENT_NAME") or os.getenv("GITEA_EVENT_NAME") or "" + event_path = os.getenv("GITHUB_EVENT_PATH") or os.getenv("GITEA_EVENT_PATH") or "" + if not event_path: + return event_name, None + + path = pathlib.Path(event_path) + if not path.is_file(): + return event_name, None + + try: + return event_name, json.loads(path.read_text(encoding="utf-8")) + except Exception as exc: + _eprint(f"WARN: failed to parse event payload: {path} ({exc})") + return event_name, None + + +def _gather_subjects(event_name: str, payload: Optional[dict]) -> List[Tuple[str, str]]: + subjects: List[Tuple[str, str]] = [] + + if isinstance(payload, dict): + if event_name.startswith("pull_request"): + pr = payload.get("pull_request") + if isinstance(pr, dict): + title = (pr.get("title") or "").strip() + if title: + subjects.append(("pull_request.title", title.splitlines()[0].strip())) + + if event_name == "push": + commits = payload.get("commits") + if isinstance(commits, list): + for commit in commits: + if not isinstance(commit, dict): + continue + msg = (commit.get("message") or "").strip() + if not msg: + continue + subject = msg.splitlines()[0].strip() + sha = commit.get("id") or commit.get("sha") or "" + label = f"push.commit {sha[:7]}" if sha else "push.commit" + subjects.append((label, subject)) + + if subjects: + return subjects + + try: + subjects.append(("HEAD", _git("log", "-1", "--format=%s", "HEAD"))) + except Exception: + pass + return subjects + + +def main() -> int: + try: + root = _repo_root() + except Exception as exc: + _eprint(f"ERROR: not a git repository: {exc}") + return 2 + + os.chdir(root) + + require_emoji = os.getenv("COMMIT_LINT_REQUIRE_EMOJI", "1") not in ("0", "false", "False") + + try: + spec_path = _find_commit_spec(root) + except FileNotFoundError as exc: + _eprint(f"ERROR: {exc}") + return 2 + + try: + mapping = _parse_type_emoji_mapping(spec_path.read_text(encoding="utf-8")) + except Exception as exc: + _eprint(f"ERROR: failed to read/parse {spec_path}: {exc}") + return 2 + + event_name, payload = _load_event_payload() + subjects = _gather_subjects(event_name, payload) + + print(f"commit spec: {spec_path}") + if event_name: + print(f"event: {event_name}") + print(f"require emoji: {require_emoji}") + print(f"checks: {len(subjects)} subject(s)") + + errors: List[str] = [] + for label, subject in subjects: + err = _validate_subject_line(subject, mapping, require_emoji=require_emoji) + if err: + errors.append(f"- {label}: {err}\n subject: {subject}") + + if errors: + _eprint("ERROR: commit message lint failed:") + for item in errors: + _eprint(item) + return 1 + + print("OK") + return 0 + + +if __name__ == "__main__": + raise SystemExit(main()) + diff --git a/templates/ci/gitea/.gitea/workflows/standards-check.yml b/templates/ci/gitea/.gitea/workflows/standards-check.yml new file mode 100644 index 0000000..b8d00cd --- /dev/null +++ b/templates/ci/gitea/.gitea/workflows/standards-check.yml @@ -0,0 +1,19 @@ +name: Standards Check + +on: + push: + pull_request: + +jobs: + commit-message: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + with: + fetch-depth: 0 + - name: Lint commit message / PR title + env: + COMMIT_LINT_REQUIRE_EMOJI: "1" + run: | + python3 .gitea/ci/commit_message_lint.py +