e956cb7 · Oversight

Enforce source comment style

Add a comment-style scanner for strict source paths, wire it into pytest and GitHub Actions, and document the guard in CONTRIBUTING.

Co-authored-by: Codex (GPT-5.4) <noreply@openai.com>

e956cb7 Zion Boggan committed on May 18, 2026 (1 month ago)

.github/workflows/source-style.yml +14 -0

		@@ -0,0 +1,14 @@
	+	name: source-style
	+
	+	on:
	+	pull_request:
	+	push:
	+	branches: [main]
	+
	+	jobs:
	+	comments:
	+	runs-on: ubuntu-latest
	+	steps:
	+	- uses: actions/checkout@v4
	+	- name: Enforce strict source comment policy
	+	run: python scripts/check_source_comments.py

CHANGELOG.md +3 -0

		@@ -36,6 +36,9 @@
		- Code comment style. Added `CONTRIBUTING.md` guidance to prefer
		self-explanatory code and tests over prose-style inline comments, then
		removed noisy implementation comments from the Rust registry path.
	+	- Source comment guard. Added `scripts/check_source_comments.py`, a pytest
	+	wrapper, and a `source-style` GitHub Actions workflow so strict comment-light
	+	paths fail CI if prose comments are reintroduced.

		## v0.4.11 - 2026-05-08 Hardware-keys completion: Python parity, browser support, end-to-end seal

CONTRIBUTING.md +3 -0

		@@ -16,3 +16,6 @@ code first.
		sentences and implementation diary notes.

		Public documentation belongs in `docs/`, not in source-file commentary.
	+
	+	The strictest paths are enforced by `scripts/check_source_comments.py`; run it
	+	before pushing changes in the Rust registry.

scripts/check_source_comments.py +67 -0

		@@ -0,0 +1,67 @@
	+	#!/usr/bin/env python3
	+	"""Fail when strict source paths gain prose comments."""
	+
	+	from __future__ import annotations
	+
	+	import argparse
	+	from pathlib import Path
	+
	+
	+	ROOT = Path(__file__).resolve().parents[1]
	+	STRICT_COMMENT_FREE_DIRS = (
	+	ROOT / "oversight-rust" / "oversight-registry" / "src",
	+	)
	+	RUST_EXTENSIONS = {".rs"}
	+	COMMENT_PREFIXES = ("//", "///", "//!")
	+
	+
	+	def iter_source_files() -> list[Path]:
	+	files: list[Path] = []
	+	for directory in STRICT_COMMENT_FREE_DIRS:
	+	if directory.exists():
	+	files.extend(
	+	path
	+	for path in directory.rglob("*")
	+	if path.is_file() and path.suffix in RUST_EXTENSIONS
	+	)
	+	return sorted(files)
	+
	+
	+	def comment_violations(path: Path) -> list[tuple[int, str]]:
	+	violations: list[tuple[int, str]] = []
	+	for lineno, line in enumerate(path.read_text(encoding="utf-8").splitlines(), start=1):
	+	stripped = line.lstrip()
	+	if stripped.startswith(COMMENT_PREFIXES):
	+	violations.append((lineno, line.rstrip()))
	+	return violations
	+
	+
	+	def main() -> int:
	+	parser = argparse.ArgumentParser(description=__doc__)
	+	parser.add_argument(
	+	"--list-paths",
	+	action="store_true",
	+	help="Print strict paths before checking.",
	+	)
	+	args = parser.parse_args()
	+
	+	if args.list_paths:
	+	for directory in STRICT_COMMENT_FREE_DIRS:
	+	print(directory.relative_to(ROOT))
	+
	+	failures: list[str] = []
	+	for path in iter_source_files():
	+	for lineno, line in comment_violations(path):
	+	failures.append(f"{path.relative_to(ROOT)}:{lineno}: {line}")
	+
	+	if failures:
	+	print("Comment-style violations:")
	+	print("\n".join(failures))
	+	return 1
	+
	+	print("source comment style ok")
	+	return 0
	+
	+
	+	if __name__ == "__main__":
	+	raise SystemExit(main())

tests/test_source_comment_style.py +17 -0

		@@ -0,0 +1,17 @@
	+	import subprocess
	+	import sys
	+	from pathlib import Path
	+
	+
	+	ROOT = Path(__file__).resolve().parents[1]
	+
	+
	+	def test_strict_source_paths_are_comment_light():
	+	result = subprocess.run(
	+	[sys.executable, "scripts/check_source_comments.py"],
	+	cwd=ROOT,
	+	text=True,
	+	capture_output=True,
	+	check=False,
	+	)
	+	assert result.returncode == 0, result.stdout + result.stderr