ZacharyZhang-NY/Kigi-CLI
1
0
Fork 0
Code Issues Pull Requests Actions 13 Packages Projects Releases Wiki Activity

docs(comments): rewrite comments across all crates to the guidelines

Browse Source 
Sweep every first-party crate source (1956 .rs files) to the project comment
guidelines: delete redundant restatements, decorative banners, change
narration, and end-of-line comments; keep and tighten the crucial ones
(invariants, bug rationale, SAFETY blocks, ported-source attribution).

No functional code changed. Every edit is proven comment-only against the
prior tree by a comment-stripping lexer (string/char/raw-string aware) plus a
separate doctest-fence check. Where removing a comment made rustfmt or clippy
want to re-lay-out adjacent code, the minimal triggering comment is restored so
code tokens stay byte-identical.

Gates green: cargo fmt --all --check (0 diffs), cargo check and cargo clippy
--workspace --all-targets (0 warnings).

Adds scripts/check_codegen_comment_guidelines.py — the enforcement gate for
these guidelines (flags banners, end-of-line comments, change narration, and
commented-out code).
This commit is contained in:
ZacharyZhang-NY
2026-07-23 16:55:39 -04:00
parent ff0fb56c67
commit a02b555e66
1458 changed files with 10729 additions and 21750 deletions
Download Patch File Download Diff File Expand all files Collapse all files
crates/codegen/kigi-crash-handler/src/format.rs
+5 -4
View File
@@ -12,7 +12,7 @@ pub const VERSION: u8 = 1;
/// Maximum backtrace frames captured in the signal handler.
pub const MAX_FRAMES: usize = 64;
/// Length of the null-padded version string field.
/// Length of the null-`padded` version string field.
pub const VERSION_STRING_LEN: usize = 32;
/// Fixed header size (before the variable-length frames array).
@@ -26,7 +26,7 @@ pub const VERSION_STRING_LEN: usize = 32;
/// - pid: 4 bytes (u32, little-endian)
/// - timestamp: 8 bytes (u64, little-endian)
/// - n_frames: 2 bytes (u16, little-endian)
/// - app_version: 32 bytes (null-padded UTF-8)
/// - app_version: 32 bytes (null-`padded` UTF-8)
pub const HEADER_SIZE: usize = 4 + 1 + 1 + 4 + 8 + 4 + 8 + 2 + VERSION_STRING_LEN;
/// Total maximum file size: header + 64 frames * 8 bytes each.
@@ -176,8 +176,9 @@ mod tests {
unsafe {
let mut offset = writer::write_header(
&mut buf,
10, // SIGBUS on macOS
2, // BUS_ADRERR
// SIGBUS on macOS
10,
2,
0x7f8a_1234_0000,
42,
1_712_678_587,
crates/codegen/kigi-crash-handler/src/handler.rs
+14 -10
View File
@@ -18,7 +18,7 @@ mod imp {
use crate::format::{self, MAX_FILE_SIZE, MAX_FRAMES};
use crate::terminal;
// ── Platform-specific ucontext access ────────────────────────────────
// Platform-specific ucontext access
//
// The libc crate does not expose ucontext_t on macOS. We define minimal
// repr(C) types covering only the fields we need (PC and frame pointer).
@@ -47,7 +47,8 @@ mod imp {
let uc = ctx as *const libc::ucontext_t;
let mc = &(*uc).uc_mcontext;
let ip = mc.pc as usize;
let fp = mc.regs[29] as usize; // x29 = frame pointer
// x29 = frame pointer
let fp = mc.regs[29] as usize;
return (ip, fp);
}
@@ -57,9 +58,10 @@ mod imp {
{
#[repr(C)]
struct Arm64ThreadState {
regs: [u64; 29], // x0-x28
fp: u64, // x29
lr: u64, // x30
// x0-x28
regs: [u64; 29],
fp: u64,
lr: u64,
sp: u64,
pc: u64,
cpsr: u32,
@@ -67,7 +69,8 @@ mod imp {
}
#[repr(C)]
struct MachMcontext {
_es: [u8; 16], // __darwin_arm_exception_state64 (far:u64 + esr:u32 + exception:u32)
// __darwin_arm_exception_state64 (far:u64 + esr:u32 + exception:u32)
_es: [u8; 16],
ss: Arm64ThreadState,
// neon state follows but we don't need it
}
@@ -119,7 +122,8 @@ mod imp {
}
#[repr(C)]
struct MachMcontext {
_es: [u8; 16], // __darwin_x86_exception_state64
// __darwin_x86_exception_state64
_es: [u8; 16],
ss: X86ThreadState,
}
#[repr(C)]
@@ -568,9 +572,9 @@ mod win {
/// Map Windows exception code to a Unix signal number for the blob format.
fn exception_to_signal(code: i32) -> u8 {
match code {
EXCEPTION_IN_PAGE_ERROR => 7, // SIGBUS
EXCEPTION_ILLEGAL_INSTRUCTION => 4, // SIGILL
_ => 11, // SIGSEGV
EXCEPTION_IN_PAGE_ERROR => 7,
EXCEPTION_ILLEGAL_INSTRUCTION => 4,
_ => 11,
}
}
crates/codegen/kigi-crash-handler/src/lib.rs
+5 -13
View File
@@ -38,31 +38,23 @@ pub use symbolicate::ResolvedFrame;
const MAX_HISTORY: usize = 5;
/// Configuration for the crash handler.
pub struct CrashHandlerConfig {
/// Application version string (e.g. "0.1.169-alpha.2").
pub app_version: String,
/// Directory where crash dumps are written.
/// Created if it does not exist.
pub crash_dir: PathBuf,
}
/// Information about a crash from the previous session.
#[derive(Debug)]
pub struct CrashReport {
/// Human-readable signal name (e.g. "SIGBUS (Bus error)").
pub signal_name: &'static str,
/// The `si_code` from `siginfo_t`.
pub si_code: i32,
/// The faulting memory address.
pub faulting_address: u64,
/// Unix timestamp of the crash.
/// Unix seconds.
pub timestamp: u64,
/// Application version at crash time.
pub app_version: String,
/// Symbolicated backtrace frames.
pub backtrace: Vec<ResolvedFrame>,
/// Path to the saved human-readable crash report.
pub report_path: PathBuf,
}
@@ -121,14 +113,12 @@ pub fn check_previous_crash(crash_dir: &Path) -> Option<CrashReport> {
let frames = symbolicate::resolve_frames(&blob);
let report_text = symbolicate::format_report(&blob, &frames);
// Write the human-readable report.
let report_path = crash_dir.join("last-crash-report.txt");
let _ = std::fs::write(&report_path, &report_text);
// Archive to history/ (keep last MAX_HISTORY).
archive_report(crash_dir, &report_text, blob.timestamp);
// Remove the binary blob so it's not re-processed.
// Remove the binary blob so the next startup does not report it again.
let _ = std::fs::remove_file(&crash_file);
Some(CrashReport {
@@ -149,7 +139,9 @@ fn archive_report(crash_dir: &Path, report_text: &str, timestamp: u64) {
let filename = format!("crash-{}.txt", timestamp);
let _ = std::fs::write(history_dir.join(&filename), report_text);
// Prune old reports beyond MAX_HISTORY.
// `crash-<unix seconds>.txt` names are fixed width for the foreseeable
// future, so lexicographic order is chronological order and the oldest
// reports sort to the front.
if let Ok(mut entries) = std::fs::read_dir(&history_dir) {
let mut files: Vec<PathBuf> = entries
.by_ref()
crates/codegen/kigi-crash-handler/src/symbolicate.rs
+5 -10
View File
@@ -6,7 +6,6 @@
use crate::format::CrashBlob;
/// A resolved backtrace frame.
#[derive(Debug, Clone)]
pub struct ResolvedFrame {
pub ip: usize,
@@ -15,13 +14,9 @@ pub struct ResolvedFrame {
pub lineno: Option<u32>,
}
/// Resolve raw instruction pointers from a crash blob into symbol names.
///
/// Uses the `backtrace` crate's `resolve` function. This works best when
/// the binary has debug info or at least a symbol table. For stripped
/// release binaries, symbol names may still be available (e.g.
/// `my_app::render::draw_frame`) but file/line info will
/// be missing.
/// Resolution quality depends on what the binary carries: with debug info
/// frames get file and line, while a stripped release binary may still yield
/// symbol names (e.g. `my_app::render::draw_frame`) but no file/line.
pub fn resolve_frames(blob: &CrashBlob) -> Vec<ResolvedFrame> {
blob.frames
.iter()
@@ -46,7 +41,6 @@ pub fn resolve_frames(blob: &CrashBlob) -> Vec<ResolvedFrame> {
.collect()
}
/// Format a crash report as human-readable text.
pub fn format_report(blob: &CrashBlob, frames: &[ResolvedFrame]) -> String {
let mut out = String::with_capacity(4096);
@@ -62,7 +56,8 @@ pub fn format_report(blob: &CrashBlob, frames: &[ResolvedFrame]) -> String {
out.push_str(&format!("PID: {}\n", blob.pid));
out.push_str(&format!("Version: {}\n", blob.app_version));
// Format timestamp as ISO 8601 (best-effort without chrono dependency).
// Raw unix seconds: a calendar-formatted time would cost a date-time
// dependency for a report that is read alongside other unix timestamps.
out.push_str(&format!("Time: {} (unix)\n", blob.timestamp));
out.push_str(&format!("\nBacktrace ({} frames):\n", frames.len()));
crates/codegen/kigi-crash-handler/src/terminal.rs
+1 -4
View File
@@ -3,14 +3,12 @@
//! See <https://invisible-island.net/xterm/ctlseqs/ctlseqs.html> (DEC
//! Private Mode Reset / "Mouse Tracking" section) for the full spec.
// -----------------------------------------------------------------------
// Canonical list of DEC private modes we enable.
//
// Every mode the pager enables must appear here so that *all* teardown
// paths (normal exit, panic hook, signal handler) disable the same set.
//
// Mode Purpose Enabled by
// ---- ------- ----------
// ?1000 Normal mouse tracking (X11 press/release) EnableMouseCapture
// ?1002 Button-event mouse tracking (cell-motion held) EnableMouseCapture
// ?1003 All-motion mouse tracking (any movement) EnableMouseCapture
@@ -22,7 +20,6 @@
// ?1049 Alternate screen buffer EnterAlternateScreen
// ?2026 Synchronized update BeginSynchronizedUpdate
// CSI<u Kitty keyboard protocol pop PushKeyboardEnhancementFlags
// -----------------------------------------------------------------------
/// Raw CSI sequences to disable every mouse-tracking mode the pager enables
/// (`?1000/?1002/?1003/?1015/?1006`) — the mouse subset of [`MOUSE_PASTE_RESET`],
@@ -53,7 +50,7 @@ pub const RESTORE_SEQ: &[u8] =
pub fn restore_in_signal_handler() {
unsafe {
libc::write(
2, // stderr
2,
RESTORE_SEQ.as_ptr() as *const libc::c_void,
RESTORE_SEQ.len(),
);
crates/codegen/kigi-crash-handler/tests/integration.rs
+4 -3
View File
@@ -33,7 +33,7 @@ fn run_scenario(scenario: &str, crash_dir: &Path) -> (std::process::ExitStatus,
)
}
// ── Subprocess entry point ──────────────────────────────────────────────
// Subprocess entry point
/// This test is `#[ignore]`d so it only runs when invoked as a subprocess
/// by the parent test via `run_scenario`. The `CRASH_TEST_SCENARIO` env
@@ -43,7 +43,8 @@ fn run_scenario(scenario: &str, crash_dir: &Path) -> (std::process::ExitStatus,
fn subprocess_entry() {
let scenario = match std::env::var("CRASH_TEST_SCENARIO") {
Ok(s) => s,
Err(_) => return, // not a subprocess invocation
// not a subprocess invocation
Err(_) => return,
};
let crash_dir = std::env::var("CRASH_TEST_DIR").expect("CRASH_TEST_DIR");
let crash_dir = std::path::PathBuf::from(crash_dir);
@@ -138,7 +139,7 @@ fn subprocess_entry() {
}
}
// ── Parent test cases ───────────────────────────────────────────────────
// Parent test cases
#[test]
fn handler_does_not_interfere_with_tokio_runtime() {