kayg/calternal

Watch

Fork 0

DOCS: document CLI remote operation contracts and remove product names #906

New issue

Open

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

kayg commented

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

Owner

Evidence

At the #863 audit base, crates/calternal-cli/src/main.rs:77 names Apple AAE sidecars.
The public-function scan found 31 functions without adjacent docs in this package. Non-obvious examples include remote_commands.rs:238 (open_with_policy), :703 (restore), and :826 (share).

Owner rule

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

Expected behaviour

Explain the remote command policy and the effects and return values of restore and share operations. Name the sidecar format, not its vendor. Keep the command behavior and wire contract unchanged.

Test idea

Review public remote commands for documented authorization and mutation invariants. Run a source scan for product names. Keep CLI tests unchanged.

## Evidence At the #863 audit base, `crates/calternal-cli/src/main.rs:77` names Apple AAE sidecars. The public-function scan found 31 functions without adjacent docs in this package. Non-obvious examples include `remote_commands.rs:238` (`open_with_policy`), `:703` (`restore`), and `:826` (`share`). ## Owner rule Comments are documentation. Each non-obvious function needs a short, current comment. Source comments must not name third-party products. ## Expected behaviour Explain the remote command policy and the effects and return values of restore and share operations. Name the sidecar format, not its vendor. Keep the command behavior and wire contract unchanged. ## Test idea Review public remote commands for documented authorization and mutation invariants. Run a source scan for product names. Keep CLI tests unchanged.

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:48:44 +00:00

Author

Owner

Fixed the Rust comment findings in crates/calternal-cli. Document remote command policy and mutation results. Read the affected implementation and kept executable code, protocol values, and test expectations unchanged.

Commit: a71287651b87ae4c9ec8628404fdce18b3733be9.

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/calternal-cli/src/main.rs
crates/calternal-cli/src/remote_commands.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/calternal-cli`. Document remote command policy and mutation results. Read the affected implementation and kept executable code, protocol values, and test expectations unchanged. Commit: `a71287651b87ae4c9ec8628404fdce18b3733be9`. 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/calternal-cli/src/main.rs` - `crates/calternal-cli/src/remote_commands.rs` Decision: use protocol, format, and calternal domain terms in place of product names. No behavior decision. Issues remain open.

kayg commented

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

Author

Owner

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

docs: document remote command policy and mutation results (#906)

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/calternal-cli/src/main.rs
crates/calternal-cli/src/remote_commands.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: `5254dab95ac98c156b05b7c86da6fdc9dddcc76e`. This is the retained atomic commit after the final prose review; it supersedes any earlier SHA posted for this work. docs: document remote command policy and mutation results (#906) 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/calternal-cli/src/main.rs` - `crates/calternal-cli/src/remote_commands.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 remote command policy and mutation results (#906)

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#906

No description provided.

Rows
Columns