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

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 committed 2026-07-23 16:55:39 -04:00
1 parent ff0fb56c67
commit a02b555e66
1458 files changed
+10729 -21750

No files matched your search

+12 -33
View File
@@ -105,14 +105,6 @@ struct ScopedRefreshFailure {
/// minutes" (a suspend doesn't extend it).
const PERMANENT_FAILURE_TTL: StdDuration = StdDuration::from_secs(300);
/// Single source of truth for `auth.json` + the in-memory bearer.
///
/// Lock order: `refresh_lock` (async) -> the sync locks (`inner` / `refresher`
/// / `permanent_failure`), never co-held; `permanent_failure()`
/// reads `permanent_failure` first and only then `inner` (via
/// `attempted_tombstone_key`, when a tombstone is stored), never co-held. Never hold
/// a `parking_lot` guard across `.await`. Refreshers return [`RefreshOutcome`]
/// for `refresh_chain` to apply.
/// Whether a manager rooted at `path` may use the OS keyring for `scope`.
///
/// The keyring entry (`service kigi / oauth/kimi-code`) is global per OS
@@ -144,6 +136,14 @@ pub(crate) fn set_test_force_keyring_path_scope(on: bool) {
TEST_FORCE_KEYRING_PATH_SCOPE.with(|flag| flag.set(on));
}
/// Single source of truth for `auth.json` + the in-memory bearer.
///
/// Lock order: `refresh_lock` (async) -> the sync locks (`inner` / `refresher`
/// / `permanent_failure`), never co-held; `permanent_failure()`
/// reads `permanent_failure` first and only then `inner` (via
/// `attempted_tombstone_key`, when a tombstone is stored), never co-held. Never hold
/// a `parking_lot` guard across `.await`. Refreshers return [`RefreshOutcome`]
/// for `refresh_chain` to apply.
pub struct AuthManager {
/// In-memory bearer. Mutate via [`Self::with_inner_write`] or
/// [`Self::refresh_chain`]; the closure helpers' sync return type
@@ -274,8 +274,6 @@ enum LockOutcome {
Adopted(Box<KimiAuth>),
}
// ── Construction + builders ──────────────────────────────────────────
impl AuthManager {
pub fn new(kigi_home: &Path, kimi_code_config: KimiCodeConfig) -> Self {
let scope = kimi_code_config.auth_scope();
@@ -478,8 +476,6 @@ impl AuthManager {
}
}
// ── State mutation (clear, hot_swap, update) ──────────────────────
pub(crate) fn clear(&self) -> std::io::Result<()> {
self.remove_scope(&self.scope)
}
@@ -508,7 +504,7 @@ impl AuthManager {
tracing::warn!(error = %e, "auth: failed to remove session credential from keyring");
}
let disk_mutation = if let Some(_lock) = lock::try_lock_auth_file_nonblocking(&self.path) {
self.write_scope_removal(scope)? // lock released on drop
self.write_scope_removal(scope)?
} else {
ScopeRemoval::SkippedLockUnavailable
};
@@ -651,8 +647,6 @@ impl AuthManager {
self.clear_inner();
}
// ── Read methods ─────────────────────────────────────────────────
//
// | wire-bound bearer | `auth().await` / `get_valid_token().await` |
// | cached, no refresh | `current()` (5-min buffer) |
// | any in-memory bearer | `current_or_expired()` |
@@ -723,8 +717,6 @@ impl AuthManager {
is_expired_with_buffer(auth, Duration::zero())
}
// ── Persistence ───────────────────────────────────────────────────
/// Persist rotated tokens (keyring → file fallback) + cache.
///
/// Invariants:
@@ -781,7 +773,6 @@ impl AuthManager {
}
};
let mut map = map;
// One entry per scope.
tracing::debug!(scope = %self.scope, "auth: storing token");
map.insert(self.scope.clone(), auth.clone());
let write_result = write_auth_json(&self.path, &map);
@@ -821,7 +812,8 @@ impl AuthManager {
/// the auth-file lock on the mutation paths that matter.
fn strip_scope_from_file_best_effort(&self) {
let Ok(mut map) = read_auth_json(&self.path) else {
return; // missing/corrupt file: nothing to strip
// missing/corrupt file: nothing to strip
return;
};
if map.remove(&self.scope).is_none() {
return;
@@ -888,8 +880,6 @@ impl AuthManager {
self.clear_inner();
}
// ── Disk I/O helpers ──────────────────────────────────────────────
/// Accept a sibling-rotated disk token. On `ServerRejected`, the
/// disk key must differ from in-memory (else no one refreshed).
pub(crate) fn try_use_disk_token(
@@ -915,8 +905,7 @@ impl AuthManager {
/// Re-read disk and try to adopt a sibling-written token, emitting
/// telemetry on success. Combines `read_disk_auth` +
/// `try_use_disk_token` + the structured log that was previously
/// duplicated at each callsite in `refresh_chain`.
/// `try_use_disk_token` + the structured adoption log.
fn try_adopt_disk_token(&self, reason: RefreshReason, msg: &str) -> Option<KimiAuth> {
let disk_auth = self.read_disk_auth();
let refreshed = self.try_use_disk_token(disk_auth.as_ref(), reason)?;
@@ -1105,8 +1094,6 @@ impl AuthManager {
try_lock_auth_file_async(&self.path, timeout).await
}
// ── Refresher setup ─────────────────────────────────────────────
/// Set up refresh capability. Call once per `Arc<AuthManager>` at
/// startup; subsequent calls are no-op via an atomic guard (so
/// per-session call sites don't reset refresher-internal state).
@@ -1155,8 +1142,6 @@ impl AuthManager {
TokenType::from_auth(self.inner.read().as_ref())
}
// ── Pre-request dispatch ──────────────────────────────────────────
/// Pre-request entry point: per-`TokenType` dispatch. For just the key:
/// [`Self::get_valid_token`].
#[tracing::instrument(skip(self), fields(token_type = tracing::field::Empty))]
@@ -1259,8 +1244,6 @@ impl AuthManager {
self.auth().await.map(|a| a.key)
}
// ── Refresh chain (single mutation point) ─────────────────────────
/// Acquire lock, double-check, try disk, then active refresh via injected refresher.
///
/// This is the single place where auth state is mutated during refresh.
@@ -1779,8 +1762,6 @@ impl AuthManager {
}
}
// ── 401 recovery entry point ──────────────────────────────────────
/// 401 recovery state machine driven by the `rejected` credential. For
/// one-shot recovery off the live bearer, use `try_recover_unauthorized()`.
pub(crate) fn unauthorized_recovery(
@@ -1797,8 +1778,6 @@ impl AuthManager {
self.unauthorized_recovery(cached).next().await.is_ok()
}
// ── Proactive refresh ─────────────────────────────────────────────
/// Spawn the background refresh task (PRD F1): a fixed
/// [`PROACTIVE_REFRESH_INTERVAL`] (60s) tick that refreshes when the
/// remaining lifetime drops below `max(300, expires_in × 0.5)` seconds