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-hunk-tracker/src/loc/mod.rs
+5 -17
View File
@@ -17,9 +17,7 @@ use chrono::{DateTime, Utc};
use serde::{Deserialize, Serialize};
use tokio::sync::mpsc;
// ---------------------------------------------------------------------------
// Enums
// ---------------------------------------------------------------------------
/// Who authored a change.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
@@ -65,7 +63,7 @@ pub enum EventType {
Added,
/// An existing hunk's content changed in place.
Updated,
/// A hunk was removed. `lines_added` / `lines_removed` are negated
/// Removal of an existing hunk. `lines_added` / `lines_removed` are negated
/// so that `SUM` zeroes out the hunk's accumulated contribution.
Removed,
}
@@ -80,9 +78,7 @@ impl std::fmt::Display for EventType {
}
}
// ---------------------------------------------------------------------------
// HunkRecord
// ---------------------------------------------------------------------------
/// A single LOC attribution record derived from a [`Hunk`].
///
@@ -126,7 +122,7 @@ pub struct HunkRecord {
pub source_type: Option<SourceType>,
/// Whether this is a new hunk or an in-place update.
pub event_type: EventType,
/// Why the hunk was removed. Only set for [`EventType::Removed`] records.
/// Reason for the removal. Only set for [`EventType::Removed`] records.
#[serde(skip_serializing_if = "Option::is_none")]
pub removal_reason: Option<HunkRemovalReason>,
}
@@ -201,9 +197,7 @@ impl HunkRecord {
}
}
// ---------------------------------------------------------------------------
// HunkRecordWriter
// ---------------------------------------------------------------------------
/// Trait for persisting [`HunkRecord`]s.
///
@@ -279,9 +273,7 @@ impl HunkRecordWriter for JsonlHunkRecordWriter {
}
}
// ---------------------------------------------------------------------------
// LocAggregate (channel-based bridge to signals)
// ---------------------------------------------------------------------------
/// Lightweight aggregate update emitted by the LOC sink for consumption by
/// an external bridge (e.g., the signals system in `kigi-shell`).
@@ -290,7 +282,7 @@ impl HunkRecordWriter for JsonlHunkRecordWriter {
/// The bridge task translates them into `SignalEvent` variants.
#[derive(Debug, Clone)]
pub enum LocAggregate {
/// Lines were added or changed (from HunkAdded or HunkContentChanged).
/// New or modified lines (from `HunkAdded` or `HunkContentChanged`).
LinesChanged {
author_type: AuthorType,
lines_added: i64,
@@ -305,9 +297,7 @@ pub enum LocAggregate {
},
}
// ---------------------------------------------------------------------------
// Sink configuration
// ---------------------------------------------------------------------------
/// Context passed to the LOC sink at spawn time.
pub struct LocSinkContext {
@@ -322,9 +312,7 @@ pub struct LocSinkContext {
pub aggregate_tx: Option<mpsc::UnboundedSender<LocAggregate>>,
}
// ---------------------------------------------------------------------------
// run_loc_sink
// ---------------------------------------------------------------------------
/// Consume [`HunkEvent`]s and write LOC attribution records.
///
@@ -344,7 +332,7 @@ pub async fn run_loc_sink(
ctx: LocSinkContext,
cancellation_token: tokio_util::sync::CancellationToken,
) {
// Accumulated (lines_added, lines_removed) per hunk_id.
// Accumulated (`lines_added`, `lines_removed`) per hunk_id.
// Used to emit negating records when hunks are rejected/superseded.
let mut acc: HashMap<HunkId, (i64, i64)> = HashMap::new();
@@ -383,7 +371,7 @@ async fn handle_event(
match event {
HunkEvent::HunkAdded { path: _, ref hunk } => {
// For new hunks, the hunk's own source is the correct attribution.
// lines_added/lines_removed are the full counts (no prior state).
// `lines_added`/`lines_removed` are the full counts (no prior state).
let record = HunkRecord::from_hunk(
hunk,
&ctx.session_id,
crates/codegen/kigi-hunk-tracker/src/loc/tests.rs
+24 -24
View File
@@ -9,9 +9,7 @@ use crate::types::{Hunk, HunkId, HunkLineInfo, HunkSource};
use super::*;
// ---------------------------------------------------------------------------
// Helpers
// ---------------------------------------------------------------------------
fn sample_agent_hunk() -> Hunk {
Hunk {
@@ -129,9 +127,7 @@ fn make_ctx() -> LocSinkContext {
}
}
// ---------------------------------------------------------------------------
// Unit tests: HunkRecord::from_hunk
// ---------------------------------------------------------------------------
#[test]
fn from_hunk_agent_edit() {
@@ -148,7 +144,8 @@ fn from_hunk_agent_edit() {
assert_eq!(record.hunk_id, HunkId::from_string("test-hunk-001".into()));
assert_eq!(record.file_path, PathBuf::from("/tmp/foo.rs"));
assert_eq!(record.hunk_start, 10);
assert_eq!(record.hunk_end, 14); // 10 + 5 - 1
// 10 + 5 - 1
assert_eq!(record.hunk_end, 14);
assert_eq!(record.lines_added, 5);
assert_eq!(record.lines_removed, 3);
assert_eq!(record.author_type, Some(AuthorType::Agent));
@@ -191,7 +188,8 @@ fn from_hunk_external() {
assert_eq!(record.prompt_index, None);
assert_eq!(record.source_type, Some(SourceType::External));
assert_eq!(record.hunk_start, 1);
assert_eq!(record.hunk_end, 4); // 1 + 4 - 1
// 1 + 4 - 1
assert_eq!(record.hunk_end, 4);
}
#[test]
@@ -244,7 +242,8 @@ fn from_hunk_pure_deletion() {
// Pure deletion: new_count == 0, so uses old_start/old_count
assert_eq!(record.hunk_start, 5);
assert_eq!(record.hunk_end, 7); // 5 + 3 - 1
// 5 + 3 - 1
assert_eq!(record.hunk_end, 7);
assert_eq!(record.lines_added, 0i64);
assert_eq!(record.lines_removed, 3i64);
}
@@ -252,7 +251,8 @@ fn from_hunk_pure_deletion() {
/// Verify that attribution_source overrides the hunk's preserved source.
#[test]
fn from_hunk_trigger_source_overrides_preserved_source() {
let hunk = sample_agent_hunk(); // hunk.source = AgentEdit
// hunk.source = AgentEdit
let hunk = sample_agent_hunk();
let trigger = HunkSource::ExternalEditOnAgentFile;
let record = HunkRecord::from_hunk(
&hunk,
@@ -273,9 +273,7 @@ fn from_hunk_trigger_source_overrides_preserved_source() {
assert_eq!(record.event_type, EventType::Updated);
}
// ---------------------------------------------------------------------------
// Sink tests
// ---------------------------------------------------------------------------
#[tokio::test]
async fn sink_processes_added_and_content_changed() {
@@ -285,7 +283,8 @@ async fn sink_processes_added_and_content_changed() {
let hunk = sample_agent_hunk();
let mut updated_hunk = sample_agent_hunk();
updated_hunk.line_info.new_count = 8; // grew from 5 to 8 lines
// grew from 5 to 8 lines
updated_hunk.line_info.new_count = 8;
// Send a mix of events — only HunkAdded and HunkContentChanged should produce records
tx.send(HunkEvent::FileAdded {
@@ -302,8 +301,10 @@ async fn sink_processes_added_and_content_changed() {
path: PathBuf::from("/tmp/foo.rs"),
hunk: Arc::new(updated_hunk),
trigger_source: HunkSource::AgentEdit { prompt_index: 2 },
prev_lines_added: 5, // original hunk had 5 lines added
prev_lines_removed: 3, // original hunk had 3 lines removed
// original hunk had 5 lines added
prev_lines_added: 5,
// original hunk had 3 lines removed
prev_lines_removed: 3,
})
.unwrap();
tx.send(HunkEvent::HunkMoved {
@@ -377,7 +378,8 @@ async fn sink_removed_hunk_zeroes_out_accumulated_total() {
let ctx = make_ctx();
let cancel = tokio_util::sync::CancellationToken::new();
let hunk = sample_agent_hunk(); // lines_added=5, lines_removed=3
// lines_added=5, lines_removed=3
let hunk = sample_agent_hunk();
let hunk_id = hunk.id.clone();
let path = hunk.path.clone();
@@ -429,12 +431,14 @@ async fn sink_removed_hunk_after_updates_zeroes_correctly() {
let ctx = make_ctx();
let cancel = tokio_util::sync::CancellationToken::new();
let hunk = sample_agent_hunk(); // lines_added=5, lines_removed=3
// lines_added=5, lines_removed=3
let hunk = sample_agent_hunk();
let hunk_id = hunk.id.clone();
let path = hunk.path.clone();
let mut updated = sample_agent_hunk();
updated.line_info.new_count = 8; // grew from 5 → 8
// grew from 5 → 8
updated.line_info.new_count = 8;
// Add → update → remove
tx.send(HunkEvent::HunkAdded {
@@ -478,7 +482,8 @@ async fn sink_accepted_hunk_preserves_loc() {
let ctx = make_ctx();
let cancel = tokio_util::sync::CancellationToken::new();
let hunk = sample_agent_hunk(); // lines_added=5, lines_removed=3
// lines_added=5, lines_removed=3
let hunk = sample_agent_hunk();
let hunk_id = hunk.id.clone();
let path = hunk.path.clone();
@@ -576,7 +581,8 @@ async fn sink_shrinking_hunk_produces_negative_delta() {
.sum();
assert_eq!(agent_total, 10);
assert_eq!(human_total, -3);
assert_eq!(agent_total + human_total, 7); // net lines in file
// net lines in file
assert_eq!(agent_total + human_total, 7);
}
#[tokio::test]
@@ -615,9 +621,7 @@ async fn sink_drains_on_cancellation() {
assert!(w.flush_count > 0, "Writer should be flushed on shutdown");
}
// ---------------------------------------------------------------------------
// JSONL round-trip test
// ---------------------------------------------------------------------------
#[tokio::test]
async fn jsonl_round_trip() {
@@ -687,9 +691,7 @@ async fn jsonl_writer_appends() {
assert_eq!(lines.len(), 2);
}
// ---------------------------------------------------------------------------
// Deserialization validation
// ---------------------------------------------------------------------------
/// Invalid enum values must be rejected during deserialization.
/// This validates that the serde enum gate works — a typo like "foo"
@@ -728,9 +730,7 @@ fn deserialize_rejects_invalid_source_type() {
assert!(result.is_err(), "Should reject invalid source_type");
}
// ---------------------------------------------------------------------------
// Writer failure resilience
// ---------------------------------------------------------------------------
/// The sink must continue processing events even when the writer fails.
/// This validates the "log warning and drop the record" error policy.