kayg/calternal

Watch

Fork 0

DOCS: document Mail crypto APIs and remove provider names #930

New issue

Open

opened 2026-10-02 17:40:45 +00:00 by kayg · 2 comments

kayg commented

2026-10-02 17:40:45 +00:00

Owner

Evidence

At the #863 audit base, the public-function scan found 28 functions in crates/plugins/mail/src without adjacent docs. Non-obvious examples include crypto.rs:122,149 (encrypt and decrypt) and cache/store.rs:293 (create_account).
A case-sensitive scan found two comment lines that name a mail provider: imap.rs:176 and sync.rs:205.

Owner rule

Comments are documentation. Each non-obvious function needs a short, current comment. Source comments must not name third-party products.

Expected behaviour

Document encrypted credential layout and account persistence invariants. Describe provider-specific observed behavior without naming the provider. Keep Mail protocol and storage behavior unchanged.

Test idea

Review comments against the existing Mail crypto, sync, and store tests. Run a source scan for product names. Do not change encryption or sync expectations.

## Evidence At the #863 audit base, the public-function scan found 28 functions in `crates/plugins/mail/src` without adjacent docs. Non-obvious examples include `crypto.rs:122,149` (`encrypt` and `decrypt`) and `cache/store.rs:293` (`create_account`). A case-sensitive scan found two comment lines that name a mail provider: `imap.rs:176` and `sync.rs:205`. ## Owner rule Comments are documentation. Each non-obvious function needs a short, current comment. Source comments must not name third-party products. ## Expected behaviour Document encrypted credential layout and account persistence invariants. Describe provider-specific observed behavior without naming the provider. Keep Mail protocol and storage behavior unchanged. ## Test idea Review comments against the existing Mail crypto, sync, and store tests. Run a source scan for product names. Do not change encryption or sync expectations.

kayg referenced this issue

2026-10-02 17:44:36 +00:00

Audit: module docs and stale comments (comments are docs) #863

kayg commented

2026-10-02 17:55:55 +00:00

Author

Owner

Fixed the Rust comment findings in crates/plugins/mail. Document credential envelopes and connected account persistence. Read the affected implementation and kept executable code, protocol values, and test expectations unchanged.

Commit: 0e98f9fa41441364448d0a25450dbbfe61056a69.

Verification: cargo fmt --check exited 0; output was empty. A source comparison with full-line comments removed matched before and after for every changed file.

Files:

crates/plugins/mail/src/cache/store.rs
crates/plugins/mail/src/crypto.rs
crates/plugins/mail/src/imap.rs
crates/plugins/mail/src/sync.rs

Decision: use protocol, format, and calternal domain terms in place of product names. No behavior decision. Issues remain open.

Fixed the Rust comment findings in `crates/plugins/mail`. Document credential envelopes and connected account persistence. Read the affected implementation and kept executable code, protocol values, and test expectations unchanged. Commit: `0e98f9fa41441364448d0a25450dbbfe61056a69`. Verification: `cargo fmt --check` exited 0; output was empty. A source comparison with full-line comments removed matched before and after for every changed file. Files: - `crates/plugins/mail/src/cache/store.rs` - `crates/plugins/mail/src/crypto.rs` - `crates/plugins/mail/src/imap.rs` - `crates/plugins/mail/src/sync.rs` Decision: use protocol, format, and calternal domain terms in place of product names. No behavior decision. Issues remain open.

kayg referenced this issue from a commit

2026-10-02 17:56:13 +00:00

docs: document credential envelopes and Connected Account persistence (#930)

kayg commented

2026-10-02 18:02:39 +00:00

Author

Owner

Rust comment fixes are complete on job/docsfix-rust. Final commit: 1578a60c3142b5b18f5c561e65b880d1be2a35a9. This is the retained atomic commit after the final prose review; it supersedes any earlier SHA posted for this work.

docs: document credential envelopes and Connected Account persistence (#930)

All executable source and test expectations are unchanged. The final comparison against origin/dev confirmed only full-line comments and blank lines changed. The audited product-name scan passed across non-vendored Rust comments.

Gate: cargo fmt --check exited 0. Verbatim stdout and stderr are empty:

Files:

crates/plugins/mail/src/cache/store.rs
crates/plugins/mail/src/crypto.rs
crates/plugins/mail/src/imap.rs
crates/plugins/mail/src/sync.rs

Decision: describe existing behavior with protocol, format, and calternal domain terms; no behavior or design change. No build or behavior tests ran, as required by this comment-only job. No issue is closed.

Rust comment fixes are complete on `job/docsfix-rust`. Final commit: `1578a60c3142b5b18f5c561e65b880d1be2a35a9`. This is the retained atomic commit after the final prose review; it supersedes any earlier SHA posted for this work. docs: document credential envelopes and Connected Account persistence (#930) All executable source and test expectations are unchanged. The final comparison against `origin/dev` confirmed only full-line comments and blank lines changed. The audited product-name scan passed across non-vendored Rust comments. Gate: `cargo fmt --check` exited 0. Verbatim stdout and stderr are empty: ```text ``` Files: - `crates/plugins/mail/src/cache/store.rs` - `crates/plugins/mail/src/crypto.rs` - `crates/plugins/mail/src/imap.rs` - `crates/plugins/mail/src/sync.rs` Decision: describe existing behavior with protocol, format, and calternal domain terms; no behavior or design change. No build or behavior tests ran, as required by this comment-only job. No issue is closed.

kayg referenced this issue

2026-10-02 18:02:42 +00:00

Audit: module docs and stale comments (comments are docs) #863

kayg referenced this issue from a commit

2026-10-02 18:10:46 +00:00

docs: document credential envelopes and Connected Account persistence (#930)

No labels

No milestone

No project

No assignees

1 participant

Notifications

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference

kayg/calternal#930

No description provided.

Rows
Columns