Struct ContentState 

pub struct ContentState { /* private fields */ }

What: The candidates of one invocation once prepared, or the remembered failure. Option<Result<..>> is “not yet asked”, “prepared” or “failed”. Why: Every content policy of the invocation reads the same version through one store.

In TS you’d write (pseudocode):

class ContentState { #prepared?: PreparedCandidates | CandidateError }

Implementations

impl ContentState

What: impl ContentState { ... } attaches the constructor and the two reads. Why: Preparation and reading stay behind one owner, so no policy can read bytes of a version it did not get from here.

In TS you’d write (pseudocode):

class ContentState { version(lifecycle, facts) {} bytes(candidate) {} }

pub fn new() -> ContentState

What: A state that has prepared nothing. Why: Preparation waits until a content policy reads.

In TS you’d write (pseudocode):

constructor() {}

pub fn prepare<F: RepositoryFacts>( &mut self, lifecycle: &LifecycleContent, facts: &mut F, ) -> Result<Option<Rc<CandidateVersion>>, CandidateError>

What: The candidate version, prepared on first use; Ok(None) when the lifecycle has no candidates. <F: RepositoryFacts> accepts any facts provider; Err(error) is the candidate layer’s failure, remembered for later calls. Why: A direct command prepares its scope before any policy runs, as the installed wrapper does, and reports a failure as a lifecycle failure of its own.

In TS you’d write (pseudocode):

async prepare(lifecycle: LifecycleContent, facts: RepositoryFacts): Promise<CandidateVersion | undefined>; // throws CandidateError

pub fn version<F: RepositoryFacts>( &mut self, lifecycle: &LifecycleContent, facts: &mut F, ) -> Result<Option<Rc<CandidateVersion>>, PolicyOutcome>

What: The candidate version for a content policy: as prepare, with a failure turned into the outcome the policy returns as it is. Why: The first content policy that reads pays for the preparation; later ones share it, and a failure is reported the same way to each.

In TS you’d write (pseudocode):

async version(lifecycle: LifecycleContent, facts: RepositoryFacts): Promise<CandidateVersion | undefined>; // throws PolicyOutcome

pub fn bytes( &mut self, candidate: &Candidate, ) -> Result<Rc<[u8]>, PolicyOutcome>

What: The bytes of a candidate of the prepared version, with corrections applied. Why: Bytes come from the store bound to the private index, never the live worktree, unless a correction of this invocation replaced them.

In TS you’d write (pseudocode):

async bytes(candidate: Candidate): Promise<Uint8Array>;

pub fn real_index(&self) -> Option<&Path>

What: The real index the prepared candidates were copied from, once prepared. Why: A direct fix proves that installing its corrections left that index unchanged.

In TS you’d write (pseudocode):

get realIndexPath(): string | undefined;

impl ContentState

What: impl ContentState { ... } continued: corrections of a fixing lifecycle. Why: A policy proposes, the fix loop applies after the pass, and later passes read the corrected bytes; nothing reaches the worktree until the fix installs them.

In TS you’d write (pseudocode):

class ContentState { propose(c) {} takeProposals() {} apply(cs) {} }

pub fn propose(&mut self, correction: Correction)

What: Record one correction a policy proposes in the current pass. Why: Corrections wait until the pass ends, so every policy of the pass reads the same bytes.

In TS you’d write (pseudocode):

propose(correction: Correction): void;

pub fn take_proposals(&mut self) -> Vec<Correction>

What: Hand over the current pass’s proposals and forget them. std::mem::take moves the list out and leaves an empty one behind. Why: Each pass starts with no proposals, and a proposal is applied at most once.

In TS you’d write (pseudocode):

takeProposals(): Correction[];

pub fn apply(&mut self, corrections: Vec<Correction>)

What: Apply corrections in order. A file whose correction restores its original bytes is no longer corrected. Why: The corrected map then equals another state’s map exactly when both states hold the same bytes in every file, which the fix loop’s cycle check needs. A file’s original is the bytes its first correction replaced; a file restored and corrected again replaces those same bytes.

In TS you’d write (pseudocode):

apply(corrections: Correction[]): void;

pub fn corrected_state(&self) -> BTreeMap<Vec<u8>, InstallChange>

What: A copy of every corrected file, by pathname. Copies share the bytes. Why: The fix loop keeps one per changed state to recognize a repeated state.

In TS you’d write (pseudocode):

correctedState(): Map<string, InstallChange>;

pub fn install_changes(&self) -> Vec<InstallChange>

What: Every corrected file, in Git’s byte order of pathnames. Why: These are the changes a converged fix installs, and the order its summary lists them in.

In TS you’d write (pseudocode):

installChanges(): InstallChange[];

impl ContentState

What: impl ContentState { ... } continued: the scan of every scannable candidate. Why: The scan pass reads bytes through the store the candidates were prepared in, with this invocation’s corrections laid over it.

In TS you’d write (pseudocode):

class ContentState { scan(scanner, rulesPath) {} }

pub fn scan( &mut self, scanner: &CandidateScanner, rules_path: Option<&[u8]>, ) -> Result<Vec<CandidateScan>, ScanRunError>

What: Scan the prepared version through scanner. Option<&[u8]> is the rules file’s own pathname, which is not scanned, or nothing. Why: scan_version is the candidate layer’s one scan pass; this lends it the store and the version together.

In TS you’d write (pseudocode):

async scan(scanner: CandidateScanner, rulesPath?: Buffer): Promise<CandidateScan[]>;

impl ContentState

What: impl ContentState { ... } continued: the whole candidate state, for a policy that reads files beyond the candidates. Why: The dependent-version policy lists every tracked file of the private index and reads files that are not candidates, through the same store and the same corrections every other content policy reads through.

In TS you’d write (pseudocode):

class ContentState { storeWithCorrections() {} }

pub fn store_with_corrections( &mut self, ) -> Option<(&mut CandidateStore, &BTreeMap<Vec<u8>, InstallChange>)>

What: The store the candidates were prepared in, with this invocation’s corrected files; nothing before preparation or after a failed one. The two borrows are of separate fields, so both can be held at once. Why: A later pass of a direct fix must read what the earlier passes made of every file, candidate or not.

In TS you’d write (pseudocode):

storeWithCorrections(): [CandidateStore, Map<string, InstallChange>] | undefined;

Trait Implementations

impl Default for ContentState

What: impl Default for ContentState lets ContentState::default() build the empty state. Why: Clippy asks a type with a new() without arguments to provide Default too.

In TS you’d write (pseudocode):

static default(): ContentState { return new ContentState(); }

fn default() -> ContentState

What: The state that has prepared nothing. Why: same as new.

In TS you’d write (pseudocode):

static default(): ContentState