21 fix help flag output and run binary only behavior

.github/workflows/build.yml

@@ -34,6 +34,11 @@ jobs:
         echo "LLVM_DIR=/usr/lib/llvm-20/lib/cmake/llvm" >> $GITHUB_ENV
         echo "Clang_DIR=/usr/lib/llvm-20/lib/cmake/clang" >> $GITHUB_ENV
 
+    - name: Compute next version (SemVer)
+      id: semver
+      run: |
+        python3 scripts/ci/semver_check.py
+
     - name: Set up QEMU (Linux)
       if: runner.os == 'Linux'
       uses: docker/setup-qemu-action@v3
@@ -90,7 +95,7 @@ jobs:
         python3 test/examples/test_extern_project.py
 
     - name: Docker tests (multi-arch, Linux)
-      if: runner.os == 'Linux'
+      if: runner.os == 'Linux' && github.event_name == 'push' && github.ref == 'refs/heads/main'
       run: |
         docker buildx build --platform linux/amd64 -f test/docker/Dockerfile . --progress=plain --output=type=cacheonly
         docker buildx build --platform linux/arm64 -f test/docker/Dockerfile . --progress=plain --output=type=cacheonly

.github/workflows/commit-check.yml

@@ -0,0 +1,16 @@
+name: Commit conventions
+
+on:
+  push:
+
+jobs:
+  commit_check:
+    name: Check conventional commits
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - name: Validate commit messages
+        run: |
+          python3 scripts/ci/commit_checker.py

.pre-commit-config.yaml

@@ -0,0 +1,9 @@
+repos:
+  - repo: local
+    hooks:
+      - id: conventional-commit-msg
+        name: conventional commit message
+        entry: python3 scripts/git/commit_msg_checker.py
+        language: system
+        stages: [commit-msg]
+        pass_filenames: true

CMakeLists.txt

@@ -209,7 +209,8 @@ else()
   )
 endif()
 
-add_executable(cc src/cli/main.cc)
+add_executable(cc src/cli/main.cc src/cli/help.cc src/cli/args.cc)
+target_include_directories(cc PRIVATE src)
 
 # Propagate CLANG_RESOURCE_DIR as a compile definition to all relevant targets
 foreach(tgt compilerlib_static compilerlib_shared cc)

CONTRIBUTING.md

@@ -0,0 +1,27 @@
+# Contributing
+
+## Commit message convention
+We enforce Conventional Commits in CI and via a local commit-msg hook.
+
+Allowed types:
+- feat, fix, chore, docs, refactor, perf, ci, build, style, revert, test
+
+Rules:
+- Format: `<type>(<scope>)?: <subject>`
+- Subject line length: **max 72 characters**
+
+Examples:
+- `feat(cli): improve --help output`
+- `fix: handle missing output path`
+
+## Local setup (recommended)
+We use pre-commit to install a commit-msg hook.
+
+Option (script):
+```
+./scripts/setup-dev.sh
+```
+
+## CI
+CI runs `scripts/ci/commit_checker.py` on every push and will fail if any commit
+message is not Conventional or exceeds the subject length limit.

scripts/ci/commit_checker.py

@@ -0,0 +1,211 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+
+import json
+import os
+import re
+import subprocess
+import sys
+from dataclasses import dataclass
+from typing import Iterable, List, Optional, Tuple
+
+ALLOWED_TYPES = (
+    "feat",
+    "fix",
+    "chore",
+    "docs",
+    "refactor",
+    "perf",
+    "ci",
+    "build",
+    "style",
+    "revert",
+    "test",
+)
+
+MAX_SUBJECT_LEN = 72
+
+CONVENTIONAL_RE = re.compile(
+    r"^(?P<type>" + "|".join(ALLOWED_TYPES) + r")"
+    r"(?P<scope>\([^)]+\))?"
+    r"(?P<breaking>!)?: "
+    r"(?P<subject>.+)$"
+)
+
+
+@dataclass
+class Commit:
+    sha: str
+    subject: str
+    body: str
+
+
+@dataclass
+class InvalidCommit:
+    commit: Commit
+    reason: str
+
+
+def run_git(args: List[str]) -> str:
+    try:
+        out = subprocess.check_output(["git", *args], text=True).strip()
+    except subprocess.CalledProcessError as exc:
+        print(exc.output, file=sys.stderr)
+        raise
+    return out
+
+
+def get_event_range() -> Optional[str]:
+    override = os.environ.get("CHECK_RANGE")
+    if override:
+        return override
+
+    event = os.environ.get("GITHUB_EVENT_NAME", "")
+    if event == "pull_request":
+        event_path = os.environ.get("GITHUB_EVENT_PATH")
+        if not event_path or not os.path.exists(event_path):
+            return None
+        with open(event_path, "r", encoding="utf-8") as fh:
+            payload = json.load(fh)
+        base_sha = payload.get("pull_request", {}).get("base", {}).get("sha")
+        head_sha = payload.get("pull_request", {}).get("head", {}).get("sha")
+        if base_sha and head_sha:
+            return f"{base_sha}..{head_sha}"
+        return None
+
+    if event == "push":
+        before = os.environ.get("GITHUB_BEFORE")
+        head = os.environ.get("GITHUB_SHA")
+        if before and head and not is_zero_sha(before):
+            return f"{before}..{head}"
+        if head:
+            return None
+
+    return None
+
+
+def is_zero_sha(value: str) -> bool:
+    return re.fullmatch(r"0+", value or "") is not None
+
+
+def range_for_ref(ref: str) -> str:
+    try:
+        run_git(["rev-parse", f"{ref}^"])
+    except subprocess.CalledProcessError:
+        return ref
+    return f"{ref}^..{ref}"
+
+
+def get_upstream_ref() -> Optional[str]:
+    try:
+        upstream = run_git(["rev-parse", "--abbrev-ref", "--symbolic-full-name", "@{u}"])
+    except subprocess.CalledProcessError:
+        return None
+    return upstream or None
+
+
+def find_base_ref() -> Optional[str]:
+    explicit = os.environ.get("BASE_BRANCH")
+    candidates: List[str] = []
+    if explicit:
+        candidates.extend([explicit, f"origin/{explicit}"])
+
+    upstream = get_upstream_ref()
+    if upstream:
+        candidates.append(upstream)
+
+    candidates.extend(["origin/main", "origin/master", "main", "master"])
+
+    seen = set()
+    for ref in candidates:
+        if ref in seen:
+            continue
+        seen.add(ref)
+        try:
+            run_git(["rev-parse", "--verify", ref])
+            return ref
+        except subprocess.CalledProcessError:
+            continue
+    return None
+
+
+def compute_branch_range() -> str:
+    base_ref = find_base_ref()
+    if not base_ref:
+        return range_for_ref("HEAD")
+    try:
+        base_sha = run_git(["merge-base", "HEAD", base_ref])
+    except subprocess.CalledProcessError:
+        return range_for_ref("HEAD")
+    if not base_sha:
+        return range_for_ref("HEAD")
+    return f"{base_sha}..HEAD"
+
+
+def iter_commits(range_spec: Optional[str]) -> Iterable[Commit]:
+    args = ["log", "--format=%H%x1f%s%x1f%b%x1e"]
+    if range_spec:
+        args.insert(1, range_spec)
+    raw = run_git(args)
+    if not raw:
+        return []
+    commits: List[Commit] = []
+    for record in raw.split("\x1e"):
+        record = record.strip()
+        if not record:
+            continue
+        parts = record.split("\x1f")
+        if len(parts) < 2:
+            continue
+        sha = parts[0]
+        subject = parts[1]
+        body = parts[2] if len(parts) > 2 else ""
+        commits.append(Commit(sha=sha, subject=subject, body=body))
+    return commits
+
+
+def is_merge_commit(commit: Commit) -> bool:
+    subject = commit.subject
+    return subject.startswith("Merge ") or subject.startswith("Merge pull request")
+
+
+def validate_commits(commits: Iterable[Commit]) -> List[InvalidCommit]:
+    invalid: List[InvalidCommit] = []
+    for commit in commits:
+        if is_merge_commit(commit):
+            continue
+        if len(commit.subject) > MAX_SUBJECT_LEN:
+            invalid.append(
+                InvalidCommit(
+                    commit=commit,
+                    reason=f"subject too long ({len(commit.subject)} > {MAX_SUBJECT_LEN})",
+                )
+            )
+            continue
+        if not CONVENTIONAL_RE.match(commit.subject):
+            invalid.append(InvalidCommit(commit=commit, reason="invalid conventional format"))
+    return invalid
+
+
+def main() -> int:
+    check_range = get_event_range()
+    if not check_range:
+        check_range = compute_branch_range()
+    print(f"Commit check range: {check_range}")
+    commits = list(iter_commits(check_range))
+    invalid = validate_commits(commits)
+    if invalid:
+        print("Non-conventional commits detected:", file=sys.stderr)
+        for entry in invalid:
+            print(
+                f"- {entry.commit.sha[:7]} {entry.commit.subject} ({entry.reason})",
+                file=sys.stderr,
+            )
+        return 1
+
+    print("All commits follow Conventional Commits.")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())