Trait Workspace 

pub trait Workspace {
    // Required methods
    fn package(&self) -> Option<&str>;
    fn current_version(&self) -> Option<&Version>;
    fn parsed_control(&self) -> Result<Control, Error>;
    fn parsed_changelog(&self) -> Result<ChangeLog, Error>;
    fn parsed_copyright(&self) -> Result<Copyright, Error>;
    fn parsed_upstream_metadata(&self) -> Result<YamlFile, Error>;
    fn parsed_watch(&self) -> Result<ParsedWatchFile, Error>;
    fn parsed_rules(&self) -> Result<Makefile, Error>;
    fn source_format(&self) -> Result<Option<String>, Error>;
    fn control(&self) -> Result<Box<dyn Editor<Control> + '_>, Error>;
    fn changelog(&self) -> Result<Box<dyn Editor<ChangeLog> + '_>, Error>;
    fn debcargo(
        &self,
    ) -> Result<Option<Box<dyn Editor<DocumentMut> + '_>>, Error>;
    fn read_file(&self, rel: &Path) -> Result<Option<Cow<'_, [u8]>>, Error>;
    fn write_file(&self, rel: &Path, content: &[u8]) -> Result<(), Error>;
    fn list_dir(&self, rel: &Path) -> Result<Option<Vec<String>>, Error>;
    fn file_mode(&self, rel: &Path) -> Result<Option<u32>, Error>;

    // Provided methods
    fn parsed_patches_series(&self) -> Result<Option<Series>, Error> { ... }
    fn parsed_patch(
        &self,
        rel: &Path,
    ) -> Result<Option<(Option<PatchHeader>, Patch)>, Error> { ... }
    fn parsed_debcargo(&self) -> Result<Option<DocumentMut>, Error> { ... }
    fn walk_dir(&self, rel: &Path) -> Result<Option<Vec<PathBuf>>, Error> { ... }
    fn base_path(&self) -> Option<&Path> { ... }
}

Access to a Debian source package, as seen by a fixer.

Each typed accessor returns an editor for a well-known file. Callers can also reach less-common files via read_file / write_file.

Required Methods

fn package(&self) -> Option<&str>

The source package name, as read from debian/changelog.

Returns None when the changelog is missing or unreadable. Hosts that legitimately don’t have a changelog (e.g. an LSP that lost access to it) should return None rather than fabricating a name.

fn current_version(&self) -> Option<&Version>

The current version of the package, as read from debian/changelog.

Returns None when the changelog is missing or unreadable.

fn parsed_control(&self) -> Result<Control, Error>

Read debian/control and return a parsed value.

Returns Err(Error::NotFound) if the file is missing — detectors typically want that exact response.

Parsing is relaxed: syntax errors are tolerated and the resulting AST may have missing or partially-recovered nodes. Detectors that need to reject malformed input should validate the structure they care about (e.g. that the source paragraph or a particular field exists) rather than expecting Err.

Implementations may cache the parse; the returned value is owned (Control is cheap to clone — its rowan green nodes are shared internally).

fn parsed_changelog(&self) -> Result<ChangeLog, Error>

Read debian/changelog and return a parsed value.

Returns Err(Error::NotFound) if the file is missing. Parsing is relaxed; see parsed_control for details on what that means.

fn parsed_copyright(&self) -> Result<Copyright, Error>

Read debian/copyright and return a parsed value.

Returns Err(Error::NotFound) if the file is missing, and Err(Error::Parse) only when the file isn’t a machine-readable DEP-5 document at all (i.e. doesn’t start with Format:). Parsing is otherwise relaxed; see parsed_control for details on what that means.

fn parsed_upstream_metadata(&self) -> Result<YamlFile, Error>

Read debian/upstream/metadata and return its parsed YAML.

Returns Err(Error::NotFound) if the file is missing or unparseable.

fn parsed_watch(&self) -> Result<ParsedWatchFile, Error>

Read debian/watch and return a parsed value.

Returns Err(Error::NotFound) if the file is missing.

fn parsed_rules(&self) -> Result<Makefile, Error>

Read debian/rules and return the parsed Makefile.

Returns Err(Error::NotFound) if the file is missing. Uses Makefile::read_relaxed, mirroring the behaviour every fixer currently expects from debian/rules parsing.

fn source_format(&self) -> Result<Option<String>, Error>

Read the trimmed contents of debian/source/format.

Returns Ok(None) if the file is missing. The default format (1.0) is not substituted — callers see exactly what is on disk so they can distinguish “no file” from “explicit 1.0”.

fn control(&self) -> Result<Box<dyn Editor<Control> + '_>, Error>

Open debian/control for editing.

Takes &self so that fixers can hold an editor and still call other workspace methods (read_file, …). Implementations that need to record edits on the workspace itself should use interior mutability.

Detectors don’t need this — they emit Actions for the appliers to run. Use parsed_control instead.

fn changelog(&self) -> Result<Box<dyn Editor<ChangeLog> + '_>, Error>

Open debian/changelog for editing. See control.

fn debcargo(&self) -> Result<Option<Box<dyn Editor<DocumentMut> + '_>>, Error>

Open debian/debcargo.toml for editing.

Returns Ok(None) if the file does not exist. Returns Err if the file exists but cannot be parsed.

fn read_file(&self, rel: &Path) -> Result<Option<Cow<'_, [u8]>>, Error>

Read raw bytes of an arbitrary file relative to the package root.

Returns Ok(None) if the file does not exist.

The returned Cow is borrowed when the host has the bytes already in memory (an LSP host with the file open in an editor buffer) and owned when they had to be fetched (a disk read). Detectors that need owned bytes can call .into_owned().

fn write_file(&self, rel: &Path, content: &[u8]) -> Result<(), Error>

Write raw bytes to an arbitrary file relative to the package root.

Creates the file if it does not exist.

fn list_dir(&self, rel: &Path) -> Result<Option<Vec<String>>, Error>

List the entries of a directory relative to the package root.

Returns the file (and subdirectory) names within rel, without any path prefix. Returns Ok(None) if the directory does not exist.

The order of returned entries is unspecified — a non-Tree host (an LSP) may not have a meaningful directory ordering.

fn file_mode(&self, rel: &Path) -> Result<Option<u32>, Error>

Read the Unix file mode of rel, or None if the file is missing.

Hosts that don’t track a meaningful mode (e.g. an LSP serving an in-memory buffer) may return Ok(None) even when the file exists. Detectors that key off mode (e.g. checking that debian/rules is executable) treat that the same as “not present” and skip.

Provided Methods

fn parsed_patches_series(&self) -> Result<Option<Series>, Error>

Read and parse debian/patches/series, the quilt patch series.

Returns Ok(None) if the file does not exist (the package ships no quilt patches). Returns Err only if the file exists but cannot be read as a series.

fn parsed_patch( &self, rel: &Path, ) -> Result<Option<(Option<PatchHeader>, Patch)>, Error>

Read a quilt patch file and return its parsed DEP-3 header together with the parsed diff.

rel is the patch’s path relative to the package root (e.g. debian/patches/fix-foo.patch), as obtained by joining debian/patches with a name from parsed_patches_series.

Returns Ok(None) when the file does not exist. On success the tuple’s first element is the patch’s DEP-3 header, or None when the patch carries no header (a bare diff) or its header does not parse — the header is optional metadata. The second element is the lossless parse of the diff body; that parser is error-recovering, so a Patch is produced even for a malformed diff.

Returns Err(Error::Parse) if the file exists but is not valid UTF-8.

fn parsed_debcargo(&self) -> Result<Option<DocumentMut>, Error>

Read debian/debcargo.toml and return a parsed TOML document.

Returns Ok(None) if the file does not exist (package is not a debcargo-managed crate). Returns Err if the file exists but cannot be parsed.

fn walk_dir(&self, rel: &Path) -> Result<Option<Vec<PathBuf>>, Error>

Recursively walk rel, returning the relative paths of every regular file beneath it (paths are relative to the package root, not to rel).

Symbolic links and other non-regular entries are skipped. Returns Ok(None) if rel does not exist.

The order of returned paths is unspecified. Hosts that can’t meaningfully walk a tree (e.g. an LSP that only knows about open buffers) may return only the files they currently track.

fn base_path(&self) -> Option<&Path>

On-disk root for hosts that have one.

Returns Some for the lintian-brush CLI ([FsWorkspace]) where the package has been materialised to disk. Returns None for in-memory hosts (an LSP serving open buffers); detectors that genuinely need to walk the source tree (e.g. an upstream-metadata guesser, a license scanner) should treat None as “skip — we can’t help here”.

Prefer the typed accessors (read_file, list_dir, …) wherever possible. Reach for this only when an external library insists on a &Path for the whole tree.

Dyn Compatibility

This trait is dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors

impl Workspace for FsWorkspace