From e70576d3bde0f970082541747b056a82ddc7d22a Mon Sep 17 00:00:00 2001
From: "coderabbitai[bot]"
 <136622811+coderabbitai[bot]@users.noreply.github.com>
Date: Thu, 1 Oct 2026 20:15:45 +0000
Subject: [PATCH] docs: Document language compliance scanner and logging
 helpers

---
 check-language-compliance-log.jl | 22 ++++++++++++++++++++++
 check-language-compliance.sh     |  7 ++++++-
 2 files changed, 28 insertions(+), 1 deletion(-)

diff --git a/check-language-compliance-log.jl b/check-language-compliance-log.jl
index 6eb37b7..3be4924 100644
--- a/check-language-compliance-log.jl
+++ b/check-language-compliance-log.jl
@@ -5,12 +5,34 @@
 using Base.Filesystem: JL_O_RDONLY, JL_O_WRONLY, JL_O_CREAT, JL_O_DIRECTORY,
     JL_O_NOFOLLOW, JL_O_NONBLOCK, JL_O_CLOEXEC
 
+"""
+Open `name` relative to directory descriptor `dirfd` using POSIX `flags` and
+return a file descriptor that the caller must close. Absolute names ignore
+`dirfd`. When creating a file, `mode` specifies permissions subject to the umask.
+Throw a `SystemError` if the operating system rejects the open.
+"""
 function openat(dirfd, name, flags, mode=0o600)
     result = ccall(:openat, Cint, (Cint, Cstring, Cint, Cuint), dirfd, name, flags, mode)
     Base.systemerror("openat $name", result == -1)
     return result
 end
 
+"""
+Create or truncate a private report and return a writable stream for the caller
+to close. `state_dir` is the full, absolute report directory, normally ending in
+`scripts/language-compliance`; `log_name` uses eight digits followed by `.log`
+(the calendar date is not validated).
+
+Create missing directories with mode `0700`, subject to the umask, and set the
+final directory to `0700`. Reject `.` and `..` components and directory symlinks;
+the final three directory components must belong to the invoking user. The log
+must be a regular file owned by that user with one hard link, and must not be a
+symlink. Set its mode to `0600` and truncate it only after validation.
+
+Throw on invalid arguments or unsafe paths/files, and propagate errors from
+opening, inspecting, changing permissions or truncating. Directory creation and
+permission changes may remain after failure; no fallback log is returned.
+"""
 function private_log(state_dir, log_name)
     isabspath(state_dir) || error("state directory must be absolute")
     occursin(r"^[0-9]{8}\.log$", log_name) || error("invalid log name")
diff --git a/check-language-compliance.sh b/check-language-compliance.sh
index 70c88aa..4a9f194 100755
--- a/check-language-compliance.sh
+++ b/check-language-compliance.sh
@@ -30,7 +30,12 @@ FFI_VIOLATIONS=0
 COMPLIANT_REPOS=0
 TOTAL_REPOS=0
 
-# Check a single repository
+# Scan repository directory $1 recursively for potential API/ABI/FFI language
+# violations and print the findings to stdout. Update API_VIOLATIONS,
+# ABI_VIOLATIONS, FFI_VIOLATIONS, COMPLIANT_REPOS and TOTAL_REPOS in the current
+# shell; initialise these counters before calling. A completed call returns the
+# final echo's status, not a compliance result. With set -e active, incrementing
+# a zero counter returns status 1 and can terminate the scan early.
 check_repo() {
     local repo_path="$1"
     local repo_name="$(basename "$repo_path")"