mirror of
https://github.com/anomalyco/opencode.git
synced 2026-11-19 08:39:02 +03:00
docs(cli-rs): state the invariants behind asynchronous reads
Replace old model and deviation labels with the actual conditions: a cursor can become stale, a read can be overtaken by an event, and an unlocked writer can change the file being replaced. Remove the same tracking references from comments on UI behavior.
This commit is contained in:
@@ -666,7 +666,6 @@ mod sys {
|
||||
/// handler was set, or the console closing.
|
||||
const CONTROL_C_EXIT: u32 = 0xC000_013A;
|
||||
|
||||
/// The parent is this binary again: a small binary of its own was not built (synthesis 4.5 prices both).
|
||||
pub fn supervise(raw: Vec<OsString>, restart: Restart) -> Result<Vec<OsString>, i32> {
|
||||
let Ok(exe) = std::env::current_exe() else { return Ok(raw) };
|
||||
// Before any client starts: Ctrl+C reaches every process on the console, and the client owns it; the end of
|
||||
|
||||
@@ -54,8 +54,7 @@ pub enum Output {
|
||||
|
||||
type Validate<'a, V> = Box<dyn Fn(&V) -> Option<String> + 'a>;
|
||||
|
||||
/// A caller's text (session titles, provider names, server messages, URLs) without escape sequences or control
|
||||
/// characters, before the prompt styles it. Clack writes it raw (`parity/deviations/O89-terminal-text.md`).
|
||||
/// Strips terminal escape sequences and controls from untrusted text before styling it.
|
||||
fn clean(text: impl Into<String>) -> String {
|
||||
let text: String = text.into();
|
||||
opencode_ui::terminal_text(&text).into_owned()
|
||||
|
||||
@@ -166,14 +166,9 @@ fn with_lock<T>(state: &Path, file: &Path, f: impl FnOnce() -> io::Result<T>) ->
|
||||
// How often [`rewrite`] reads again after another client changed the file under it.
|
||||
const REWRITE_ATTEMPTS: usize = 5;
|
||||
|
||||
// Rewrites `file` atomically with `change(text)` when that gives a new text. The TypeScript TUI writes
|
||||
// without the lock (deviation O89-jsonl-writes), so the replace happens only while the file still holds
|
||||
// what was read. Otherwise the change is made again against a new read. Contents, not metadata: a
|
||||
// TypeScript rewrite truncates in place and may keep the length, and on Windows the modification time
|
||||
// can stay within one clock tick. The new text is synced before the rename, so a crash leaves the old
|
||||
// file or the new one.
|
||||
// A client that appends to the old file between the check and the rename writes to the open old file;
|
||||
// the lines it gained are carried over to the end of the new one.
|
||||
// Rewrites atomically from the current bytes, retrying if they changed during the edit. An unlocked writer can
|
||||
// preserve both size and timestamp. Sync before renaming; a concurrent append through the old inode can still be
|
||||
// lost between the final check and rename.
|
||||
fn rewrite(file: &Path, mut change: impl FnMut(&str) -> Option<String>) -> io::Result<()> {
|
||||
for _ in 0..REWRITE_ATTEMPTS {
|
||||
let mut old = match fs::File::open(file) {
|
||||
|
||||
@@ -77,8 +77,6 @@ mod tests {
|
||||
use opentui::prelude::*;
|
||||
use opentui::testing::TestApp;
|
||||
|
||||
// Expected (bigboi notes): the kind each diagram showed goes once the host frees its block, so N diagrams drawn
|
||||
// and removed leave nothing.
|
||||
#[test]
|
||||
fn removed_diagrams_leave_no_kinds() {
|
||||
let app = TestApp::new(80, 200);
|
||||
|
||||
@@ -28,8 +28,7 @@ pub const DEFAULT_REPLAY_LIMIT: u32 = 200;
|
||||
/// `LOCAL_REPLAY_ROW_LIMIT`: rows printed only locally (errors, prompts in flight) that a resize replays.
|
||||
pub const LOCAL_ROW_LIMIT: usize = 100;
|
||||
pub const RESIZE_DELAY: Duration = Duration::from_millis(250);
|
||||
/// The events a resize replay holds while it lists. TS holds any number
|
||||
/// (`parity/deviations/O92-mini-relist-overflow.md`).
|
||||
/// Maximum events buffered during a resize replay.
|
||||
pub const RELIST_LIMIT: usize = 4096;
|
||||
|
||||
/// A part of a message whose text arrives in pieces (`FragmentRef`).
|
||||
@@ -507,8 +506,8 @@ impl Transcript {
|
||||
if commit.message_id.as_ref().is_some_and(|message| self.message_ids.contains(message)) {
|
||||
return None;
|
||||
}
|
||||
// A prompt the list did not have yet counts as shown, so it does not print again once listed. TS does not
|
||||
// record it (`parity/deviations/O89-mini-restored-prompt.md`).
|
||||
// Mark the restored prompt as shown even when the snapshot lacks it, so a later listing cannot print it
|
||||
// twice.
|
||||
if commit.kind == EntryKind::User
|
||||
&& let Some(message) = &commit.message_id
|
||||
{
|
||||
|
||||
@@ -1169,8 +1169,6 @@ mod tests {
|
||||
assert_eq!(capture.cell(0, 2).unwrap().fg, entry_color(&commit, &theme));
|
||||
}
|
||||
|
||||
/// A table is borderless columns two cells apart in both modes, as TS's top-level Markdown draws it. The `-:` column
|
||||
/// is right-aligned, where TS on Core 0.8.4 left-aligns it (`parity/deviations/OT2112-table-alignment.md`).
|
||||
#[test]
|
||||
fn tables_are_borderless_columns() {
|
||||
let commit = assistant("", Phase::Final);
|
||||
@@ -1191,9 +1189,6 @@ mod tests {
|
||||
}
|
||||
}
|
||||
|
||||
/// Mini hides the tildes of `~~x~~` and strikes the text through, in every theme and body: native code strikes
|
||||
/// `markup.strikethrough` unless a style turns the bit off, which a Rust `Style` cannot. TS mini on Core 0.8.4
|
||||
/// draws the text plain (`parity/deviations/OT2079-strikethrough.md`).
|
||||
#[test]
|
||||
fn strikethrough_text_is_struck() {
|
||||
let full = crate::theme::resolve(&crate::theme::ThemeInput {
|
||||
|
||||
@@ -1,8 +1,5 @@
|
||||
//! Stderr while the split footer is up. A `--print-logs` record or any other write to stderr would draw over the
|
||||
//! footer, so each line becomes a row of the scrollback above it instead. TS mini captures only stdout
|
||||
//! (`externalOutputMode: "capture-stdout"`); see `parity/deviations/O89-mini-stderr.md`.
|
||||
//!
|
||||
//! Only this process's writes are captured: a standalone server started before mini keeps the real stderr.
|
||||
//! Routes stderr to scrollback while the split footer owns the terminal. A server started before mini keeps its own
|
||||
//! stderr.
|
||||
|
||||
/// One line written to stderr, without its line ending. The app's message handlers receive it.
|
||||
pub struct Line(pub String);
|
||||
|
||||
@@ -44,8 +44,7 @@ pub enum Error {
|
||||
NotTheServer { pid: u32, file: PathBuf },
|
||||
}
|
||||
|
||||
/// Stops the service registered in `file`, if any. A live pid that is not that service's process
|
||||
/// (a stale registration whose pid was reused) is never signalled (deviation O89-service-stop-pid).
|
||||
/// Stops the registered service. Never signal a PID that has been reused by another process.
|
||||
pub async fn stop(transport: Arc<dyn Transport>, file: &Path, pty: Pty, poll: Poll) -> Result<(), Error> {
|
||||
let info = registration::read(file);
|
||||
if let Some(info) = &info
|
||||
|
||||
@@ -118,9 +118,8 @@ impl State {
|
||||
}
|
||||
|
||||
impl Data {
|
||||
/// Reads pending forms once per invalidation: a session's, or the global forms of a location
|
||||
/// (the default one for `None`). Forms created or settled while the read was in flight win over
|
||||
/// the snapshot (model M1, deviation O89-list-snapshots).
|
||||
/// Reads pending forms for a session or location. Forms created or settled during the read take precedence over
|
||||
/// its snapshot.
|
||||
pub fn form_sync(&self, owner: &str, location: Option<&Location>) -> Task<()> {
|
||||
let location = location.cloned().unwrap_or_else(|| self.read(|state| state.default_location().clone()));
|
||||
let owner = owner.to_owned();
|
||||
|
||||
@@ -958,9 +958,8 @@ fn edit_session(event: &V2Event) -> Option<&SessionID> {
|
||||
}
|
||||
|
||||
impl Data {
|
||||
/// Reads the newest page of a transcript once per invalidation (`message.sync`). What events
|
||||
/// created or edited while the read was in flight is merged by `durable.seq` (models M2,
|
||||
/// deviation O89-transcript-refresh, see [`State::publish_head`]).
|
||||
/// Reads the newest transcript page once per invalidation. Merge concurrent events by `durable.seq`; see
|
||||
/// [`State::publish_head`].
|
||||
pub fn message_sync(&self, session: &SessionID) -> Task<()> {
|
||||
let key = format!("session.message:{}", session.0);
|
||||
let begin = session.clone();
|
||||
@@ -1147,10 +1146,8 @@ impl Data {
|
||||
}
|
||||
}
|
||||
|
||||
/// Fetches older pages and publishes them once; false when cancelled before publishing. A latest-page
|
||||
/// refresh that replaced the cursor meanwhile, or a window that ended (models M2 rule 5), makes the
|
||||
/// pages stale: stitching them onto the new list would leave a gap, so the load starts again from
|
||||
/// the current cursor (deviation O89-older-page).
|
||||
/// Publishes older pages once. If a refresh changes the cursor, restart from the new cursor to avoid a gap. Returns
|
||||
/// false on cancellation before publication.
|
||||
async fn load_pages(
|
||||
data: &Data,
|
||||
session: &SessionID,
|
||||
|
||||
@@ -53,8 +53,8 @@ impl State {
|
||||
}
|
||||
|
||||
impl Data {
|
||||
/// Reads pending permissions once per invalidation (`permission.sync`). Requests asked or
|
||||
/// settled while the read was in flight win over the snapshot (deviation O89-list-snapshots).
|
||||
/// Reads pending permissions once per invalidation. Requests opened or settled during the read take precedence
|
||||
/// over its snapshot.
|
||||
pub fn permission_sync(&self, session: &SessionID) -> Task<()> {
|
||||
let (fetched, again) = (session.clone(), session.clone());
|
||||
self.overlay_sync(
|
||||
|
||||
@@ -100,8 +100,8 @@ pub fn adopt(project: &str, directory: &str, event: &WorktreeResolvedData) -> Op
|
||||
if key != parent && !key.starts_with(&format!("{parent}/")) {
|
||||
return None;
|
||||
}
|
||||
// The segments after the root's. TS slices `directory.slice(root.length + 1)`, which is wrong when
|
||||
// lowercasing changed a length (deviation O89-adopt-case-fold).
|
||||
// Case folding can change byte length, so count matching path segments rather than slicing at the root's byte
|
||||
// length.
|
||||
let subpath =
|
||||
(key != parent).then(|| directory.split('/').skip(root.split('/').count()).collect::<Vec<_>>().join("/"));
|
||||
Some((event.project_id.0.clone(), subpath))
|
||||
|
||||
@@ -122,8 +122,7 @@ impl Data {
|
||||
self.catalog_sync(Catalog::Shell, location)
|
||||
}
|
||||
|
||||
/// The `Catalog::Shell` read. A shell created or exited while it is in flight overrides the list it returns
|
||||
/// (deviation O92-shell-list), so the list never loses a new shell or brings back an exited one.
|
||||
/// Shell creation and exit events received during a list read take precedence over the snapshot.
|
||||
pub(crate) fn shell_read(&self, location: Location) -> Task<()> {
|
||||
let begin = location.clone();
|
||||
self.sync_start(
|
||||
|
||||
@@ -127,10 +127,8 @@ pub struct State {
|
||||
/// Maximum changes retained by one in-flight list read.
|
||||
pub(crate) const OVERLAY_LIMIT: usize = 1024;
|
||||
|
||||
/// What overtook one list read (model M1, deviation O89-list-snapshots): the items events added
|
||||
/// (`Some`) or settled (`None`) while it was in flight, by ID in arrival order. Only the read whose
|
||||
/// ticket it carries publishes. More than [`OVERLAY_LIMIT`] changes overflow it: the read then
|
||||
/// publishes nothing and reads again, so the bound costs a read, never an item.
|
||||
/// Changes that overtake a list read, keyed by ID in arrival order. Only the current ticket can publish. Beyond
|
||||
/// [`OVERLAY_LIMIT`], retry instead of losing an item.
|
||||
#[derive(Debug, Clone)]
|
||||
pub(crate) struct Overlay<V> {
|
||||
ticket: u64,
|
||||
@@ -648,10 +646,8 @@ impl Data {
|
||||
task
|
||||
}
|
||||
|
||||
/// A list read under an [`Overlay`] (model M1, deviation O89-list-snapshots), registered in `reads` under
|
||||
/// `read`. `fetch` reads the list and `publish` stores it with the overlay applied, unless a newer read
|
||||
/// replaced this one or `session` was deleted after it began. An overflowed overlay publishes nothing: `key`
|
||||
/// is invalidated and `again` reads again.
|
||||
/// Fetches a list and applies its overlay before publishing. Discard superseded reads and reads for deleted
|
||||
/// sessions. An overflow invalidates the key and schedules another read.
|
||||
#[allow(clippy::too_many_arguments)]
|
||||
pub(crate) fn overlay_sync<K, V, T, F>(
|
||||
&self,
|
||||
|
||||
@@ -1372,8 +1372,7 @@ fn the_checker_catches_wrong_clients() {
|
||||
assert!(missed.is_empty(), "the checker misses {missed:?}");
|
||||
}
|
||||
|
||||
/// The shrinker keeps the class of the failure it started from: a sequence that first fails on transcript order (O10)
|
||||
/// and also on permissions (the `Reversed` mutant) must not shrink to the shorter permission failure.
|
||||
/// Shrinking a transcript-order failure must not select a shorter sequence that fails only on permissions.
|
||||
#[test]
|
||||
fn the_shrinker_keeps_the_failure_class() {
|
||||
let ops = [
|
||||
@@ -1526,9 +1525,7 @@ const KNOWN: &[(&str, &str, &[Op])] = &[
|
||||
];
|
||||
|
||||
const OPEN: &[(&str, &str, &[Op])] = &[
|
||||
// O10: the stream lags behind a head page that already holds newer rows. A `step.started` delivered after the
|
||||
// read published has no page row with a known `durable.seq` to compare with, so it is appended after newer rows.
|
||||
// TS and the old `message_live` do the same (models-6 report).
|
||||
// A delayed `step.started` can arrive after a newer head page that contains no comparable `durable.seq`.
|
||||
(
|
||||
"late step after the newest page",
|
||||
"order ses_0",
|
||||
|
||||
@@ -110,12 +110,8 @@ pub fn syntax_theme(theme: &Theme) -> SyntaxTheme {
|
||||
styles
|
||||
}
|
||||
|
||||
/// The paste chip's text: the page color, dark in dark mode and light in light mode (#62930). A transparent page (the
|
||||
/// system theme) still holds the terminal's background in its channels, so the chip takes that. A transparent page
|
||||
/// without one takes the end of the neutral scale that reads better on the chip.
|
||||
///
|
||||
/// TypeScript takes the selected-row text instead, which is the light foreground on the system theme in dark mode
|
||||
/// (`parity/deviations/O89-paste-chip-contrast.md`).
|
||||
/// Paste chips use the page color for contrast. For transparent pages, use the terminal background if known or a
|
||||
/// contrasting neutral shade.
|
||||
fn paste_text(theme: &Theme) -> Color {
|
||||
let page = theme.background.base;
|
||||
if page.a == 255 {
|
||||
|
||||
@@ -308,10 +308,8 @@ pub fn added_lines(patch: &str) -> Option<usize> {
|
||||
(added == count).then_some(count)
|
||||
}
|
||||
|
||||
/// `VirtualAddedPatch`: an added file over 3,000 lines in chunks of 128 rows, unwrapped so each chunk is exactly its
|
||||
/// rows tall. Only the chunks [`Chunked::show`] puts in view are mounted; the others are blank rows of their height.
|
||||
/// Each chunk is highlighted on its own (deviation `H06-chunked-diff-highlights`). A theme restyles the mounted chunks
|
||||
/// in place and the ones mounted later take it.
|
||||
/// Virtualizes added files over 3,000 lines in unwrapped 128-row chunks. Unmounted chunks reserve their full height;
|
||||
/// mounted chunks highlight independently.
|
||||
pub struct Chunked {
|
||||
root: View,
|
||||
app: App,
|
||||
|
||||
@@ -430,10 +430,8 @@ impl<T: Clone + PartialEq + 'static> TuiKeymap<T> {
|
||||
&self.keymap
|
||||
}
|
||||
|
||||
/// The key sequences a layer's binding `key` binds, as the keymap expands it when the layer registers: a comma
|
||||
/// separates bindings, none of them empty, and each alias of [`ALIASES`] between the boundaries the engine uses
|
||||
/// (`+`, `,`, `<`, `>`, whitespace) is its key. [`Keymap::parse_key_sequence`] alone runs neither expansion, so a
|
||||
/// check of what a binding takes must judge these (review carbon new-3).
|
||||
/// Expands comma-separated bindings and key aliases at token boundaries before parsing the sequences, just as
|
||||
/// layer registration does.
|
||||
pub fn parse_binding(&self, key: &str) -> Result<Vec<Vec<opentui::keymap::KeySequencePart>>, String> {
|
||||
let bindings: Vec<&str> = match key.contains(',') {
|
||||
true => key.split(',').map(str::trim).collect(),
|
||||
|
||||
@@ -45,9 +45,6 @@ fn syntax_theme_matches_generate_syntax() {
|
||||
}
|
||||
}
|
||||
|
||||
/// The paste chip keeps the page color on its warning background under a transparent page too
|
||||
/// (`parity/deviations/O89-paste-chip-contrast.md`): the terminal's background when the system theme read one, else the
|
||||
/// neutral end that reads better on the chip. TypeScript draws the light foreground on the dark-mode system theme.
|
||||
#[test]
|
||||
fn paste_chip_text_is_the_page_color_on_a_transparent_page() {
|
||||
let tokyo = "#1a1b26 #f7768e #9ece6a #e0af68 #7aa2f7 #ad8ee6 #449dab #a9b1d6 #414868 #ff7a93 #b9f27c #ff9e64 #7da6ff #bb9af7 #0db9d7 #c0caf5";
|
||||
|
||||
Reference in New Issue
Block a user